@yeaft/webchat-agent 1.0.582 → 1.0.584

package/yeaft/person/repository.js

@@ -0,0 +1,352 @@
+import { randomUUID } from 'node:crypto';
+import { bytes, digest, fail, LIMITS, PersonError, safeError } from './contracts.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 };
+const publicDoc = doc => {
+  if (!doc) return null;
+  const { _id, ownerId, namespace, personId, ...rest } = doc;
+  return rest;
+};
+const iso = date => date instanceof Date ? date.toISOString() : date;
+const scopeFor = (ownerId, namespace) => ({ ownerId, namespace, personId: `person-${digest([namespace, ownerId]).slice(0, 32)}` });
+const fresh = () => ({ $expr: { $gt: ['$leaseUntil', '$$NOW'] } });
+const expired = () => ({ $expr: { $lte: ['$leaseUntil', '$$NOW'] } });
+const unavailableOutput = () => ({ text: '', retainedBytes: 0, observedBytes: null, complete: false, accepted: false, availability: 'unavailable', reason: 'worker-unavailable' });
+// This terminal-only path accepts a bounded public-output shape, never arbitrary trace/state data.
+const publicOutput = (output, failed) => {
+  if (!output) return unavailableOutput();
+  if (typeof output.text !== 'string' || bytes(output.text) > LIMITS.outputBytes) fail('OUTPUT_LIMIT');
+  const retainedBytes = bytes(output.text);
+  const observedBytes = output.observedBytes ?? output.bytes ?? retainedBytes;
+  if (!Number.isSafeInteger(observedBytes) || observedBytes < retainedBytes) fail('INVALID_REQUEST');
+  const usage = output.usage ? {} : null;
+  if (usage) for (const key of ['inputTokens', 'outputTokens', 'reasoningTokens', 'cacheReadTokens', 'cacheWriteTokens']) {
+    if (Number.isFinite(output.usage[key]) && output.usage[key] >= 0) usage[key] = output.usage[key];
+  }
+  const stopReason = typeof output.stopReason === 'string' && bytes(output.stopReason) <= 128 ? output.stopReason : null;
+  return failed ? { text: output.text, retainedBytes, observedBytes, complete: false, accepted: false, availability: 'captured', usage, stopReason }
+    : { text: output.text, bytes: retainedBytes, complete: true, usage, stopReason };
+};
+
+/** MongoDB is the sole authority. No Session, local transcript or memory-file fallback. */
+export class MongoPersonRepository {
+  constructor({ uri, dbName = 'yeaft_person', namespace, MongoClient, leaseMs = 15000 }) {
+    this.uri = uri; this.dbName = dbName; this.namespace = namespace; this.MongoClient = MongoClient; this.leaseMs = leaseMs;
+  }
+  async init() {
+    if (!this.initializing) this.initializing = this.connect().catch(async error => {
+      await this.client?.close().catch(() => {}); this.initializing = null;
+      throw safeError(error);
+    });
+    return this.initializing;
+  }
+  async connect() {
+    const Client = this.MongoClient || (await import('mongodb')).MongoClient;
+    this.client = new Client(this.uri, { serverSelectionTimeoutMS: 5000, connectTimeoutMS: 5000, socketTimeoutMS: 10000, maxPoolSize: 8, retryWrites: true });
+    await this.client.connect(); this.db = this.client.db(this.dbName);
+    const hello = await this.db.command({ hello: 1 });
+    if (!hello.setName && hello.msg !== 'isdbgrid') fail('STORAGE_UNAVAILABLE');
+    if (!hello.logicalSessionTimeoutMinutes) fail('STORAGE_UNAVAILABLE');
+    this.collections = {};
+    for (const name of COLLECTIONS) {
+      const fullName = `person_${name}`;
+      try {
+        await this.db.createCollection(fullName, { validator: { $jsonSchema: {
+          bsonType: 'object', required: ['schemaVersion', 'ownerId', 'namespace', 'personId'],
+          properties: { schemaVersion: { enum: [1] }, ownerId: { bsonType: 'string' }, namespace: { bsonType: 'string' }, personId: { bsonType: 'string' } },
+        } }, validationLevel: 'strict' });
+      } catch (error) { if (error.code !== 48) throw error; }
+      this.collections[name] = this.db.collection(fullName);
+    }
+    const scope = { namespace: 1, ownerId: 1, personId: 1 };
+    const unique = (name, fields) => this.collections[name].createIndex({ ...scope, ...fields }, { unique: true });
+    await Promise.all([
+      unique('persons', {}), unique('states', {}), unique('episodes', { clientMessageId: 1 }), unique('episodes', { id: 1 }),
+      unique('messages', { seq: 1 }), unique('traces', { seq: 1 }), unique('concepts', { id: 1 }),
+      this.collections.episodes.createIndex({ ...scope, inputWatermark: -1 }),
+      unique('concept_revisions', { id: 1, revision: 1 }), unique('state_commits', { version: 1 }),
+      this.collections.concepts.createIndex({ ...scope, updatedAt: -1, id: 1 }),
+    ]);
+  }
+  scope(ownerId) { return scopeFor(ownerId, this.namespace); }
+  doc(scope, values) { return { schemaVersion: 1, ...scope, ...values }; }
+  async transaction(fn) {
+    await this.init();
+    const session = this.client.startSession();
+    try { return await session.withTransaction(() => fn(session), txOptions); }
+    catch (error) { throw safeError(error); }
+    finally { await session.endSession(); }
+  }
+  personView(p) {
+    return { id: p.personId, name: p.name, soul: p.soul, soulRevision: p.soulRevision, createdAt: iso(p.createdAt), settings: p.settings };
+  }
+  async open(ownerId, name = 'Digital Person') {
+    const scope = this.scope(ownerId);
+    try {
+      return await this.transaction(async session => {
+        let p = await this.collections.persons.findOne(scope, { session });
+        if (!p) {
+          p = this.doc(scope, {
+            name, soul: 'A continuous, curious and honest digital person. Preserve uncertainty, reconsider your judgments, distinguish imagination from experience, and respect permissions. You may disagree without acting without authority.',
+            soulRevision: 1, createdAt: new Date(), settings: { autonomyEnabled: false },
+            epoch: 0, writeSerial: 0, inputWatermark: 0, controlVersion: 0, stateVersion: 0,
+            traceSeq: 0, messageSeq: 0, activeEpisodeId: null, leaseOwner: null, leaseUntil: new Date(0),
+          });
+          await this.collections.persons.insertOne(p, { session });
+          await this.collections.states.insertOne(this.doc(scope, { version: 0, summary: '', appraisal: '', focusConceptIds: [], conceptRefs: [], lastSelection: null, updatedAt: p.createdAt }), { session });
+        }
+        return { person: this.personView(p) };
+      });
+    } catch (error) {
+      // Two explicit opens may race on the deterministic unique identity.
+      const p = await this.collections?.persons.findOne(scope).catch(() => null);
+      if (p) return { person: this.personView(p) };
+      throw error;
+    }
+  }
+  async getPerson(ownerId) {
+    await this.init();
+    const p = await this.collections.persons.findOne(this.scope(ownerId));
+    if (!p) fail('NOT_OPEN');
+    return p;
+  }
+  async trace(session, p, episodeId, kind, data = {}) {
+    const scope = this.scope(p.ownerId);
+    const updated = await this.collections.persons.findOneAndUpdate(scope, { $inc: { traceSeq: 1, writeSerial: 1 } }, { session, returnDocument: 'after' });
+    const record = this.doc(scope, { id: randomUUID(), episodeId, kind, seq: updated.traceSeq, createdAt: new Date(), ...data });
+    await this.collections.traces.insertOne(record, { session });
+    return publicDoc(record);
+  }
+  async recover(ownerId) {
+    return this.transaction(async session => {
+      const scope = this.scope(ownerId);
+      const p = await this.collections.persons.findOneAndUpdate({ ...scope, activeEpisodeId: { $ne: null }, ...expired() }, {
+        $inc: { epoch: 1, writeSerial: 1 }, $set: { activeEpisodeId: null, leaseOwner: null, leaseUntil: new Date(0) },
+      }, { session, returnDocument: 'before' });
+      if (p) {
+        const episode = await this.collections.episodes.findOneAndUpdate({ ...scope, id: p.activeEpisodeId, status: 'running' },
+          { $set: { status: 'interrupted', terminalCode: 'INTERRUPTED', endedAt: new Date() } }, { session, returnDocument: 'before' });
+        await this.abandonCall(session, p, episode, 'INTERRUPTED');
+        await this.trace(session, p, p.activeEpisodeId, 'interrupted', { code: 'INTERRUPTED', reason: 'lease-expired', baseStateVersion: p.stateVersion });
+      }
+      // Cancellation leaves a bounded drain window for the original worker's consumed prefix.
+      // If that worker crashed, the next access closes the call with explicit unavailable output.
+      const abandoned = await this.collections.episodes.find({ ...scope, status: 'cancelled', 'openCall.callId': { $exists: true },
+        $expr: { $lte: ['$callFinalizeUntil', '$$NOW'] } }, { session }).toArray();
+      for (const episode of abandoned) await this.abandonCall(session, { ownerId }, episode, 'CANCELLED');
+      return Boolean(p);
+    });
+  }
+  async admit(ownerId, { kind, text, clientMessageId, workerId, budget }) {
+    await this.recover(ownerId);
+    const scope = this.scope(ownerId), requestHash = digest([kind, text]);
+    return this.transaction(async session => {
+      const existing = await this.collections.episodes.findOne({ ...scope, clientMessageId }, { session });
+      if (existing) {
+        if (existing.requestHash !== requestHash) fail('IDEMPOTENCY_CONFLICT');
+        return { episodeId: existing.id, duplicate: true, status: existing.status };
+      }
+      let p = await this.collections.persons.findOne(scope, { session });
+      if (!p) fail('NOT_OPEN');
+      if (p.activeEpisodeId) fail('BUSY');
+      // Every admission is explicit. A manual Dream request authorizes this episode
+      // only; it neither requires nor enables unsolicited background cognition.
+      const id = randomUUID();
+      p = await this.collections.persons.findOneAndUpdate({ ...scope, activeEpisodeId: null, epoch: p.epoch }, [{ $set: {
+        activeEpisodeId: id, leaseOwner: workerId, leaseUntil: { $add: ['$$NOW', this.leaseMs] },
+        epoch: { $add: ['$epoch', 1] }, writeSerial: { $add: ['$writeSerial', 1] },
+        inputWatermark: { $add: ['$inputWatermark', 1] }, messageSeq: { $add: ['$messageSeq', kind === 'send' ? 1 : 0] },
+      } }], { session, returnDocument: 'after' });
+      if (!p) fail('BUSY');
+      let messageId = null;
+      if (kind === 'send') {
+        messageId = randomUUID();
+        await this.collections.messages.insertOne(this.doc(scope, { id: messageId, revision: 1, seq: p.messageSeq, episodeId: id, role: 'user', text, createdAt: new Date(), clientMessageId }), { session });
+      }
+      const episode = this.doc(scope, { id, clientMessageId, requestHash, kind, text, messageId, status: 'running', workerId, epoch: p.epoch,
+        baseStateVersion: p.stateVersion, inputWatermark: p.inputWatermark, controlVersion: p.controlVersion, budget, createdAt: new Date() });
+      await this.collections.episodes.insertOne(episode, { session });
+      await this.trace(session, p, id, 'accepted', { trigger: { kind, text, messageId }, baseStateVersion: p.stateVersion, budget });
+      return { episodeId: id, duplicate: false, status: 'running', episode };
+    });
+  }
+  fence(episode, withLease = true) {
+    return { ...this.scope(episode.ownerId), activeEpisodeId: episode.id, epoch: episode.epoch, leaseOwner: episode.workerId,
+      stateVersion: episode.baseStateVersion, controlVersion: episode.controlVersion, inputWatermark: episode.inputWatermark, ...(withLease ? fresh() : {}) };
+  }
+  async heartbeat(episode) {
+    await this.init();
+    const p = await this.collections.persons.findOneAndUpdate(this.fence(episode), [{ $set: {
+      leaseUntil: { $add: ['$$NOW', this.leaseMs] }, writeSerial: { $add: ['$writeSerial', 1] },
+    } }], { returnDocument: 'after', writeConcern: { w: 'majority' } });
+    if (!p) fail('STALE');
+  }
+  async append(episode, kind, data) {
+    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');
+      return this.trace(session, p, episode.id, kind, data);
+    });
+  }
+  async startCall(episode, data) {
+    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 updated = await this.collections.episodes.updateOne({ ...this.scope(episode.ownerId), id: episode.id, status: 'running', openCall: { $exists: false } },
+        { $set: { openCall: { callId: data.callId, requested: data.requested, effective: data.effective, ...(data.manifest ? { manifest: data.manifest } : {}) } } }, { session });
+      if (!updated.modifiedCount) fail('STALE');
+      return this.trace(session, p, episode.id, 'call_started', data);
+    });
+  }
+  /** Close exactly the original worker's started call, even after cancel; never regain state ownership. */
+  async finalizeCall(episode, { callId, effective, output, code = null }) {
+    return this.transaction(async session => {
+      const scope = this.scope(episode.ownerId);
+      const record = await this.collections.episodes.findOne({ ...scope, id: episode.id, workerId: episode.workerId,
+        epoch: episode.epoch, 'openCall.callId': callId }, { session });
+      if (!record) return false;
+      const live = record.status === 'running' && await this.collections.persons.findOne(this.fence(episode), { session });
+      const draining = record.status === 'cancelled' && await this.collections.episodes.findOne({ ...scope, id: episode.id,
+        $expr: { $gt: ['$callFinalizeUntil', '$$NOW'] } }, { session });
+      if (!live && !draining) return false;
+      const failed = Boolean(code || !live || !output);
+      const terminalCode = !live ? 'CANCELLED' : code || 'INTERRUPTED';
+      const safeEffective = { model: record.openCall.requested.model, effort: typeof effective?.effort === 'string' && effective.effort.length <= 128 ? effective.effort : null,
+        effortObserved: effective?.effortObserved === true };
+      if (typeof effective?.wireMode === 'string' && effective.wireMode.length <= 128) safeEffective.wireMode = effective.wireMode;
+      // The episode update serializes finalizers, cancellation/recovery and duplicate workers.
+      await this.collections.episodes.updateOne({ ...scope, id: episode.id, 'openCall.callId': callId }, { $unset: { openCall: '', callFinalizeUntil: '' } }, { session });
+      await this.trace(session, { ownerId: episode.ownerId }, episode.id, failed ? 'call_failed' : 'call_output', {
+        callId, requested: record.openCall.requested, effective: safeEffective, output: publicOutput(output, failed),
+        ...(!failed && record.openCall.manifest ? { manifest: record.openCall.manifest } : {}),
+        ...(failed ? { code: new PersonError(terminalCode).code } : {}),
+      });
+      return Boolean(live);
+    });
+  }
+  async abandonCall(session, p, episode, code) {
+    if (!episode?.openCall) return;
+    await this.collections.episodes.updateOne({ ...this.scope(p.ownerId), id: episode.id, 'openCall.callId': episode.openCall.callId },
+      { $unset: { openCall: '', callFinalizeUntil: '' } }, { session });
+    await this.trace(session, p, episode.id, 'call_failed', { ...episode.openCall, code, output: unavailableOutput() });
+  }
+  async context(episode) {
+    await this.init();
+    const scope = this.scope(episode.ownerId);
+    const p = await this.collections.persons.findOne(this.fence(episode));
+    if (!p) fail('STALE');
+    const [state, messages, focused, recent] = await Promise.all([
+      this.collections.states.findOne(scope), this.collections.messages.find(scope).sort({ seq: -1 }).limit(12).toArray(),
+      this.collections.states.findOne(scope).then(s => this.collections.concepts.find({ ...scope, id: { $in: s.focusConceptIds } }).limit(12).toArray()),
+      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 };
+  }
+  async recall(ownerId, { kind = 'messages', query = '', cursor = null, limit = 5 }) {
+    const scope = this.scope(ownerId);
+    const escaped = query.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    if (kind === 'messages') return this.list(ownerId, 'messages', { cursor, limit }, query ? { text: { $regex: escaped, $options: 'i' } } : {});
+    await this.init();
+    const filter = { ...scope, ...(query ? { statement: { $regex: escaped, $options: 'i' } } : {}), ...(cursor ? { id: { $gt: cursor } } : {}) };
+    const docs = await this.collections.concepts.find(filter).sort({ id: 1 }).limit(limit + 1).maxTimeMS(2000).toArray();
+    return { items: docs.slice(0, limit).map(publicDoc), nextCursor: docs.length > limit ? docs[limit - 1].id : null };
+  }
+  async commit(episode, proposal, selection, callId, reportedSources = new Map()) {
+    return this.transaction(async session => {
+      const scope = this.scope(episode.ownerId);
+      const p = await this.collections.persons.findOneAndUpdate(this.fence(episode), { $inc: { stateVersion: 1, writeSerial: 1, messageSeq: proposal.reply ? 1 : 0 },
+        $set: { activeEpisodeId: null, leaseOwner: null, leaseUntil: new Date(0) } }, { session, returnDocument: 'after' });
+      if (!p) fail('STALE');
+      const revisions = [];
+      for (const patch of proposal.concepts) {
+        const { expectedRevision, ...fields } = patch;
+        const reportedSourceRefs = reportedSources.get(patch.id) ?? [];
+        if (patch.epistemicState === 'reported' && !reportedSourceRefs.length) fail('INVALID_PROPOSAL');
+        const record = this.doc(scope, { ...fields, reportedSourceRefs, revision: expectedRevision + 1, episodeId: episode.id, callId, stateVersion: p.stateVersion, updatedAt: new Date() });
+        if (expectedRevision === 0) {
+          if (await this.collections.concepts.findOne({ ...scope, id: patch.id }, { session })) fail('STALE');
+          await this.collections.concepts.insertOne(record, { session });
+        } else {
+          const update = await this.collections.concepts.replaceOne({ ...scope, id: patch.id, revision: expectedRevision }, record, { session });
+          if (update.matchedCount !== 1) fail('STALE');
+        }
+        await this.collections.concept_revisions.insertOne({ ...record, _id: randomUUID() }, { session });
+        revisions.push({ id: patch.id, revision: record.revision });
+      }
+      const focus = await this.collections.concepts.find({ ...scope, id: { $in: proposal.state.focusConceptIds } }, { session }).toArray();
+      if (focus.length !== proposal.state.focusConceptIds.length) fail('STALE');
+      const state = this.doc(scope, { ...proposal.state, version: p.stateVersion, conceptRefs: focus.map(c => ({ id: c.id, revision: c.revision })),
+        decision: proposal.decision, lastSelection: { model: selection.model, effort: selection.effort }, updatedAt: new Date(), episodeId: episode.id });
+      const updated = await this.collections.states.replaceOne({ ...scope, version: episode.baseStateVersion }, state, { session });
+      if (updated.matchedCount !== 1) fail('STALE');
+      await this.collections.state_commits.insertOne(this.doc(scope, { id: randomUUID(), version: p.stateVersion, parentVersion: episode.baseStateVersion,
+        episodeId: episode.id, callId, conceptRevisions: revisions, state: publicDoc(state), createdAt: new Date() }), { session });
+      if (proposal.reply) await this.collections.messages.insertOne(this.doc(scope, { id: randomUUID(), revision: 1, seq: p.messageSeq, episodeId: episode.id,
+        role: 'assistant', text: proposal.reply, createdAt: new Date() }), { session });
+      await this.collections.episodes.updateOne({ ...scope, id: episode.id, status: 'running' }, { $set: { status: 'completed', endedAt: new Date(), stateVersion: p.stateVersion } }, { session });
+      await this.trace(session, p, episode.id, 'committed', { callId, parentVersion: episode.baseStateVersion, stateVersion: p.stateVersion, conceptRevisions: revisions, decision: proposal.decision });
+      return { state: publicDoc(state) };
+    });
+  }
+  async finish(episode, status, code) {
+    return this.transaction(async session => {
+      const p = await this.collections.persons.findOneAndUpdate(this.fence(episode, false), { $inc: { writeSerial: 1, epoch: 1 },
+        $set: { activeEpisodeId: null, leaseOwner: null, leaseUntil: new Date(0) } }, { session, returnDocument: 'before' });
+      if (!p) return false; // A cancel, takeover or earlier terminal transaction already won.
+      const ended = await this.collections.episodes.findOneAndUpdate({ ...this.scope(episode.ownerId), id: episode.id, status: 'running' }, { $set: { status, terminalCode: code, endedAt: new Date() } }, { session, returnDocument: 'before' });
+      await this.abandonCall(session, p, ended, code);
+      await this.trace(session, p, episode.id, status, { code, baseStateVersion: episode.baseStateVersion });
+      return true;
+    });
+  }
+  async cancel(ownerId, episodeId = null) {
+    return this.transaction(async session => {
+      const scope = this.scope(ownerId);
+      const current = await this.collections.persons.findOne(scope, { session });
+      if (!current) fail('NOT_OPEN');
+      if (!current.activeEpisodeId || (episodeId && current.activeEpisodeId !== episodeId)) return { cancelled: false, episodeId };
+      const p = await this.collections.persons.findOneAndUpdate({ ...scope, activeEpisodeId: current.activeEpisodeId, epoch: current.epoch }, {
+        $inc: { epoch: 1, controlVersion: 1, writeSerial: 1 }, $set: { activeEpisodeId: null, leaseOwner: null, leaseUntil: new Date(0) },
+      }, { session, returnDocument: 'before' });
+      if (!p) fail('STALE');
+      await this.collections.episodes.updateOne({ ...scope, id: p.activeEpisodeId, status: 'running' }, { $set: { status: 'cancelled', terminalCode: 'CANCELLED', endedAt: new Date(), callFinalizeUntil: p.leaseUntil } }, { session });
+      await this.trace(session, p, p.activeEpisodeId, 'cancelled', { code: 'CANCELLED' });
+      return { cancelled: true, episodeId: p.activeEpisodeId };
+    });
+  }
+  async settings(ownerId, settings) {
+    return this.transaction(async session => {
+      const scope = this.scope(ownerId);
+      const p = await this.collections.persons.findOne(scope, { session });
+      if (!p) fail('NOT_OPEN');
+      if (p.activeEpisodeId) fail('BUSY'); // No implicit background API or deferred control effects.
+      const next = { ...p.settings, ...settings };
+      await this.collections.persons.updateOne(scope, { $set: { settings: next }, $inc: { controlVersion: 1, writeSerial: 1 } }, { session });
+      if (Object.keys(settings).length) await this.trace(session, p, null, 'settings', { settings: next });
+      return { settings: next };
+    });
+  }
+  async list(ownerId, collection, { cursor = null, limit = 20 }, filter = {}) {
+    await this.getPerson(ownerId);
+    const docs = await this.collections[collection].find({ ...this.scope(ownerId), ...filter, ...(cursor ? { seq: { $lt: cursor } } : {}) }).sort({ seq: -1 }).limit(limit + 1).maxTimeMS(2000).toArray();
+    return { items: docs.slice(0, limit).map(publicDoc), nextCursor: docs.length > limit ? String(docs[limit - 1].seq) : null };
+  }
+  async snapshot(ownerId) {
+    await this.recover(ownerId);
+    return this.transaction(async session => {
+      const scope = this.scope(ownerId);
+      const p = await this.collections.persons.findOne(scope, { session });
+      if (!p) fail('NOT_OPEN');
+      const state = await this.collections.states.findOne(scope, { session });
+      const messages = await this.collections.messages.find(scope, { session }).sort({ seq: -1 }).limit(21).toArray();
+      const concepts = await this.collections.concepts.find({ ...scope, id: { $in: state.focusConceptIds } }, { session }).limit(12).toArray();
+      const episode = await this.collections.episodes.findOne(scope, { session, sort: { inputWatermark: -1 },
+        projection: { _id: 0, id: 1, status: 1, terminalCode: 1, endedAt: 1 } });
+      return { latestEpisode: episode, person: this.personView(p), state: publicDoc(state), concepts: concepts.map(publicDoc), messages: messages.slice(0, 20).reverse().map(publicDoc),
+        nextMessagesCursor: messages.length > 20 ? String(messages[19].seq) : null, busy: Boolean(p.activeEpisodeId), episodeId: p.activeEpisodeId };
+    });
+  }
+  async close() { await this.client?.close(); }
+}

package/yeaft/person/runtime.js

@@ -0,0 +1,186 @@
+import { randomUUID } from 'node:crypto';
+import { CAPABILITY_MAP, PersonCapabilities, catalogRevision as capabilityCatalogRevision } from './capabilities.js';
+import { abortable, collectOutput } from './provider.js';
+import { bytes, fail, LIMITS, PersonError, PROPOSAL_INSTRUCTIONS, reportedLineage, safeError, validateProposal, validateSelection } from './contracts.js';
+
+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. */
+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.
+  const contextCap = Math.min(LIMITS.contextBytes, model.contextWindow - model.maxOutput - 1024);
+  const system = `${snapshot.person.soul}\n\n${PROPOSAL_INSTRUCTIONS}`;
+  const triggerRef = `trigger:${episode.id}`;
+  const context = {
+    person: { id: snapshot.person.id, name: snapshot.person.name, soulRevision: snapshot.person.soulRevision },
+    state: snapshot.state, trigger: { kind: episode.kind, text: episode.text, ref: triggerRef },
+    models: provider.catalog, modelCatalogRevision: provider.catalogRevision,
+    capabilities: CAPABILITY_MAP, capabilityCatalogRevision,
+    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.',
+  };
+  const sourceRefs = new Set([triggerRef, ...dependencyRefs]);
+  const renderedRefs = new Set([triggerRef]);
+  const conceptMap = new Map();
+  const sources = new Map([[triggerRef, { kind: 'trigger', reportedSourceRefs:
+    ['send', 'think'].includes(episode.kind) && episode.text?.trim() ? [triggerRef] : [] }]]);
+  const seenMessage = m => sources.set(messageRef(m), { kind: 'message', role: m.role, reportedSourceRefs: m.role === 'user' ? [messageRef(m)] : [] });
+  const seenConcept = c => {
+    conceptMap.set(c.id, c);
+    sources.set(conceptRef(c), { kind: 'concept', epistemicState: c.epistemicState,
+      reportedSourceRefs: c.epistemicState === 'reported' ? c.reportedSourceRefs ?? [] : [] });
+  };
+  const omitted = [];
+  // A selected recall result is a full bounded page. Never silently shorten it after recording tool success.
+  if (capabilityResult?.kind === 'messages') for (const m of capabilityResult.items) { sourceRefs.add(messageRef(m)); renderedRefs.add(messageRef(m)); seenMessage(m); }
+  if (capabilityResult?.kind === 'concepts') for (const c of capabilityResult.items) { sourceRefs.add(conceptRef(c)); renderedRefs.add(conceptRef(c)); seenConcept(c); }
+  context.sourceRefs = [...sourceRefs];
+  const fits = () => bytes(system) + bytes(context) <= contextCap;
+  if (!fits()) fail('CONTEXT_LIMIT');
+  const add = (field, item, ref) => {
+    if (renderedRefs.has(ref)) return;
+    const inherited = sourceRefs.has(ref);
+    context[field].push(item); if (!inherited) context.sourceRefs.push(ref);
+    if (!fits()) { context[field].pop(); if (!inherited) context.sourceRefs.pop(); omitted.push({ ref, reason: 'context-budget' }); }
+    else { sourceRefs.add(ref); renderedRefs.add(ref); if (field === 'concepts') seenConcept(item); else seenMessage(item); }
+  };
+  for (const m of [...snapshot.messages].reverse()) add('messages', m, messageRef(m));
+  context.messages.reverse();
+  for (const c of snapshot.concepts) add('concepts', c, conceptRef(c));
+  return {
+    system, messages: [{ role: 'user', content: JSON.stringify(context) }], sourceRefs, concepts: conceptMap, sources,
+    manifest: { stateVersion: snapshot.state.version, sourceRefs: [...sourceRefs], renderedSourceRefs: [...renderedRefs], inputDependencyRefs: [...sourceRefs], omitted,
+      boundedRecentWindow: { messages: 12, recentConcepts: 12, focusedConcepts: 12 },
+      contextBytes: bytes(system) + bytes(context), contextBudgetBytes: contextCap, outputTokensReserved: model.maxOutput,
+      modelCatalogRevision: provider.catalogRevision, capabilityCatalogRevision }, maxTokens: model.maxOutput,
+  };
+}
+
+export class PersonRuntime {
+  constructor({ repository, getProvider, budget }) {
+    this.repository = repository; this.getProvider = getProvider; this.budget = budget;
+    this.running = new Map(); this.workerId = randomUUID(); this.closed = false;
+  }
+  start(episode) {
+    if (this.closed) return;
+    const controller = new AbortController();
+    const job = { controller, episode, promise: null };
+    this.running.set(episode.id, job);
+    // Admission resolves independently of provider latency. No model work occurs without an explicit admission.
+    job.promise = Promise.resolve().then(() => this.run(episode, controller)).catch(() => {}).finally(() => this.running.delete(episode.id));
+  }
+  cancel(episodeId, code = 'CANCELLED') { this.running.get(episodeId)?.controller.abort(new PersonError(code)); }
+  async run(episode, controller) {
+    const { signal } = controller;
+    const timeout = setTimeout(() => controller.abort(new PersonError('TIMEOUT')), episode.budget.timeoutMs);
+    timeout.unref?.();
+    let heartbeatRunning = false;
+    const heartbeat = setInterval(async () => {
+      if (heartbeatRunning || signal.aborted) return;
+      heartbeatRunning = true;
+      try { await this.repository.heartbeat(episode); }
+      catch (error) { controller.abort(safeError(error)); }
+      finally { heartbeatRunning = false; }
+    }, Math.max(100, Math.floor(this.repository.leaseMs / 3)));
+    heartbeat.unref?.();
+    try {
+      const provider = await abortable(this.getProvider(), signal);
+      const snapshot = await abortable(this.repository.context(episode), signal);
+      let selection = { ...provider.defaultSelection, reason: 'configured-default', origin: 'bootstrap' };
+      if (snapshot.state.lastSelection) {
+        try { validateSelection(snapshot.state.lastSelection, provider.catalog); selection = { ...snapshot.state.lastSelection, reason: 'last-accepted-choice', origin: 'persisted' }; }
+        catch { await this.repository.append(episode, 'selection_rejected', { requested: snapshot.state.lastSelection, code: 'MODEL_SELECTION', fallback: 'configured-default' }); }
+      }
+      const capabilities = new PersonCapabilities(this.repository, episode.ownerId);
+      let previous = null, capabilityResult = null, dependencyRefs = [];
+      // Validation retains actual reads across calls, independently of the bounded rendered request.
+      // Candidate proposals never enter this read-set or establish new provenance.
+      const readConcepts = new Map(), readSources = new Map();
+      for (let index = 0; index < episode.budget.calls; index++) {
+        signal.throwIfAborted();
+        const callId = randomUUID();
+        const context = assembleContext({ snapshot, episode, provider, selection, previous, capabilityResult, dependencyRefs, remainingCalls: episode.budget.calls - index });
+        dependencyRefs = context.manifest.inputDependencyRefs;
+        for (const [id, concept] of context.concepts) readConcepts.set(id, concept);
+        for (const [ref, source] of context.sources) readSources.set(ref, source);
+        await this.repository.heartbeat(episode); // Revalidate distributed ownership before each dispatch.
+        const requested = { model: selection.model, effort: selection.effort };
+        const effective = { model: selection.model, effort: null, effortObserved: false };
+        await this.repository.startCall(episode, {
+          callId, callIndex: index, requested, effective, selectionOrigin: selection.origin, reason: selection.reason,
+          manifest: context.manifest, request: { system: context.system, messages: context.messages, maxTokens: context.maxTokens, tools: [] },
+          capability: previous?.next?.capability ?? null,
+        });
+        let output;
+        try {
+          signal.throwIfAborted();
+          output = await collectOutput(provider.adapter, {
+            model: selection.model, effort: selection.effort ?? undefined, effortSource: 'auto',
+            system: context.system, messages: context.messages, maxTokens: context.maxTokens, signal,
+          }, decision => { effective.effort = decision.effective; effective.effortObserved = true; effective.wireMode = decision.wireMode; });
+        } catch (error) {
+          const safe = safeError(error, 'PROVIDER_FAILED');
+          await this.repository.finalizeCall(episode, { callId, effective, code: safe.code, output: error.partialOutput }).catch(() => {});
+          throw safe;
+        }
+        // A narrow once-only finalizer can retain consumed output after cancellation, never state.
+        // Complete public output remains durable even if proposal validation subsequently rejects it.
+        if (!await this.repository.finalizeCall(episode, { callId, effective, output })) fail('STALE');
+        signal.throwIfAborted();
+        let proposal;
+        try {
+          try { proposal = JSON.parse(output.text); } catch { fail('INVALID_PROPOSAL'); }
+          validateProposal(proposal, { stateVersion: episode.baseStateVersion, sourceRefs: context.sourceRefs, concepts: readConcepts, sources: readSources, catalog: provider.catalog, dream: episode.kind === 'dream' });
+        } catch (error) {
+          const safe = safeError(error, 'INVALID_PROPOSAL');
+          await this.repository.append(episode, 'proposal_rejected', { callId, code: safe.code });
+          throw safe;
+        }
+        await this.repository.append(episode, 'activity', { callId, activity: proposal.activity, decision: proposal.decision, disposition: proposal.next ? 'candidate' : 'proposed-commit' });
+        if (!proposal.next) {
+          signal.throwIfAborted();
+          await this.repository.commit(episode, proposal, selection, callId, new Map(proposal.concepts.map(c => [c.id, c.epistemicState === 'reported' ? reportedLineage(c, readSources) : []])));
+          return;
+        }
+        if (index + 1 >= episode.budget.calls) {
+          await this.repository.finish(episode, 'budget_exhausted', 'CALL_BUDGET');
+          return;
+        }
+        previous = proposal;
+        selection = { model: proposal.next.model, effort: proposal.next.effort, reason: proposal.next.reason, origin: 'person' };
+        capabilityResult = null;
+        if (proposal.next.capability) {
+          const invocation = proposal.next.capability;
+          await this.repository.append(episode, 'capability_started', { callId, capability: invocation, access: 'read-only' });
+          try {
+            signal.throwIfAborted();
+            capabilityResult = await abortable(capabilities.execute(invocation), signal);
+            await this.repository.append(episode, 'capability_result', { callId, capability: invocation, result: capabilityResult });
+          } catch (error) {
+            const safe = safeError(error, 'UNSUPPORTED');
+            await this.repository.append(episode, 'capability_failed', { callId, capabilityId: invocation.id, code: safe.code }).catch(() => {});
+            throw safe;
+          }
+        }
+      }
+    } 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.
+      await this.repository.finish(episode, status, safe.code).catch(() => {});
+    } finally {
+      clearTimeout(timeout); clearInterval(heartbeat);
+      if (!signal.aborted) controller.abort(new PersonError('INTERRUPTED'));
+    }
+  }
+  async close() {
+    this.closed = true;
+    const jobs = [...this.running.values()];
+    for (const job of jobs) job.controller.abort(new PersonError('INTERRUPTED'));
+    await Promise.all(jobs.map(job => job.promise));
+  }
+}

package/yeaft/person/service.js

@@ -0,0 +1,101 @@
+import { MongoPersonRepository } from './repository.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
+ * 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.
+ */
+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 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 });
+  // 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 } });
+  let closed = false;
+  const requests = new Set();
+  async function handle({ ownerId, op, payload = {} } = {}) {
+    if (closed) fail('CLOSED');
+    text(ownerId, 256); // Owners are opaque authenticated IDs, not database selectors.
+    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 };
+      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 }; }
+      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 }; }
+    }
+    if (!configured) fail('NOT_CONFIGURED');
+    switch (op) {
+      case 'open': {
+        object(payload, ['name'], []);
+        if (payload.name != null) text(payload.name, 160);
+        return repository.open(ownerId, payload.name);
+      }
+      case 'snapshot': object(payload, []); return repository.snapshot(ownerId);
+      case 'send':
+      case 'think':
+      case 'dream': {
+        object(payload, op === 'dream' ? ['clientMessageId'] : ['text', 'clientMessageId'], op === 'dream' ? ['clientMessageId'] : ['text', 'clientMessageId']);
+        identifier(payload.clientMessageId);
+        if (op !== 'dream') text(payload.text, LIMITS.inputBytes, op === 'think');
+        const admitted = await repository.admit(ownerId, { kind: op, text: payload.text ?? '', clientMessageId: payload.clientMessageId,
+          workerId: runtime.workerId, budget: runtime.budget });
+        if (!admitted.duplicate) {
+          if (closed) await repository.finish(admitted.episode, 'interrupted', 'INTERRUPTED');
+          else runtime.start(admitted.episode);
+        }
+        return { episodeId: admitted.episodeId, duplicate: admitted.duplicate, status: admitted.status };
+      }
+      case 'traces': await repository.recover(ownerId); return repository.list(ownerId, 'traces', page(payload));
+      case 'messages': return repository.list(ownerId, 'messages', page(payload));
+      case 'cancel': {
+        object(payload, ['episodeId'], []);
+        if (payload.episodeId != null) identifier(payload.episodeId);
+        const result = await repository.cancel(ownerId, payload.episodeId);
+        if (result.cancelled) runtime.cancel(result.episodeId);
+        return result;
+      }
+      case 'settings': {
+        object(payload, ['autonomyEnabled'], []);
+        if (Object.values(payload).some(v => typeof v !== 'boolean')) fail('INVALID_REQUEST');
+        // Timer-driven autonomy is deliberately not claimed or silently enabled.
+        if (payload.autonomyEnabled === true) fail('UNSUPPORTED');
+        return repository.settings(ownerId, payload);
+      }
+      default: fail('INVALID_REQUEST');
+    }
+  }
+  return {
+    request(input) {
+      const pending = Promise.resolve().then(() => handle(input)).catch(error => { throw safeError(error); });
+      requests.add(pending); pending.then(() => requests.delete(pending), () => requests.delete(pending));
+      return pending;
+    },
+    async close() {
+      closed = true;
+      await Promise.allSettled([...requests]);
+      await runtime.close();
+      await repository.close().catch(() => {});
+    },
+  };
+}
+
+export { PersonError } from './contracts.js';