@xmoxmo/bncr 0.6.2 → 0.6.3

package/src/messaging/inbound/conversation-history-serial.ts

@@ -0,0 +1,258 @@
+import { emitBncrLogLine } from '../../core/logging.ts';
+
+export type ConversationHistorySerialPhase =
+  | 'queued'
+  | 'running'
+  | 'snapshot'
+  | 'shard_created'
+  | 'upload_start'
+  | 'upload_end'
+  | 'cache_delete_start'
+  | 'cache_delete_done'
+  | 'lock_clear_start'
+  | 'lock_clear_done'
+  | 'abandoned';
+
+export type ConversationHistorySerialState = {
+  historyKey: string;
+  owner?: string;
+  phase: ConversationHistorySerialPhase;
+  updatedAt: number;
+  snapshotMessageIds: string[];
+  cacheKey?: string;
+  uploadCompleted: boolean;
+  abandoned: boolean;
+};
+
+export type ConversationHistorySerialHandle = {
+  phase: (
+    phase: ConversationHistorySerialPhase,
+    data?: { snapshotMessageIds?: string[]; cacheKey?: string },
+  ) => void;
+  setCleanup: (cleanup: () => void) => void;
+  isAbandoned: () => boolean;
+  owner: () => string;
+};
+
+type BncrConversationHistorySerialEntry = {
+  chain: Promise<void>;
+  abort: (reason?: unknown) => void;
+  state: ConversationHistorySerialState;
+  cleanup?: () => void;
+};
+
+const bncrConversationHistoryChains = new Map<string, BncrConversationHistorySerialEntry[]>();
+let bncrConversationHistorySerialOwner = 'default';
+
+export function setConversationHistorySerialOwner(owner: string): void {
+  bncrConversationHistorySerialOwner = String(owner || '').trim() || 'default';
+}
+
+export function getConversationHistorySerialOwner(): string {
+  return bncrConversationHistorySerialOwner;
+}
+
+function createConversationHistorySerialHandle(entry?: BncrConversationHistorySerialEntry) {
+  return {
+    phase: (
+      phase: ConversationHistorySerialPhase,
+      data?: { snapshotMessageIds?: string[]; cacheKey?: string },
+    ) => {
+      if (!entry) return;
+      entry.state.phase = phase;
+      entry.state.updatedAt = Date.now();
+      if (data?.snapshotMessageIds) {
+        entry.state.snapshotMessageIds = data.snapshotMessageIds
+          .map((messageId) => String(messageId || '').trim())
+          .filter(Boolean);
+      }
+      if (data?.cacheKey) entry.state.cacheKey = data.cacheKey;
+      if (phase === 'upload_end') entry.state.uploadCompleted = true;
+    },
+    setCleanup: (cleanup: () => void) => {
+      if (entry) entry.cleanup = cleanup;
+    },
+    isAbandoned: () => {
+      if (!entry) return false;
+      return (
+        entry.state.abandoned === true ||
+        (Boolean(entry.state.owner) && entry.state.owner !== bncrConversationHistorySerialOwner)
+      );
+    },
+    owner: () => entry?.state.owner || bncrConversationHistorySerialOwner,
+  };
+}
+
+function isUploadCompletedPhase(state: ConversationHistorySerialState): boolean {
+  return state.uploadCompleted === true;
+}
+
+export async function runConversationHistorySerial<T>(
+  historyKey: string,
+  task: (handle: ConversationHistorySerialHandle) => Promise<T> | T,
+  meta?: { to?: string | null; debugEnabled?: boolean; owner?: string },
+) {
+  const key = String(historyKey || '').trim();
+  if (!key) return await task(createConversationHistorySerialHandle());
+
+  const serialEntries = bncrConversationHistoryChains.get(key) || [];
+  const previous = serialEntries.at(-1)?.chain || Promise.resolve();
+  // A task with no predecessor has already acquired the serial slot even before
+  // its first microtask runs. Stale-lock cleanup must be able to distinguish
+  // that active slot from genuinely queued work behind an earlier lock.
+  const hasPredecessor = serialEntries.length > 0;
+  let release!: () => void;
+  let abort!: (reason?: unknown) => void;
+  const current = new Promise<void>((resolve, reject) => {
+    release = resolve;
+    abort = reject;
+  });
+  const chain = previous.then(
+    () => current,
+    () => current,
+  );
+  const serialEntry: BncrConversationHistorySerialEntry = {
+    chain,
+    abort,
+    state: {
+      historyKey: key,
+      owner: meta?.owner || bncrConversationHistorySerialOwner,
+      phase: hasPredecessor ? 'queued' : 'running',
+      updatedAt: Date.now(),
+      snapshotMessageIds: [],
+      uploadCompleted: false,
+      abandoned: false,
+    },
+  };
+  const handle = createConversationHistorySerialHandle(serialEntry);
+  serialEntries.push(serialEntry);
+  bncrConversationHistoryChains.set(key, serialEntries);
+
+  const debugGate = () => meta?.debugEnabled === true;
+  emitBncrLogLine(
+    'info',
+    `[bncr] conversation-history-serial queued|key=${key}|to=${String(meta?.to || '-')}`,
+    { debugOnly: true },
+    debugGate,
+  );
+  try {
+    await previous.catch(() => {});
+    emitBncrLogLine(
+      'info',
+      `[bncr] conversation-history-serial acquired|key=${key}|to=${String(meta?.to || '-')}`,
+      { debugOnly: true },
+      debugGate,
+    );
+    if (serialEntry.state.abandoned) {
+      return undefined as T;
+    }
+    serialEntry.state.phase = 'running';
+    serialEntry.state.updatedAt = Date.now();
+    return await task(handle);
+  } finally {
+    emitBncrLogLine(
+      'info',
+      `[bncr] conversation-history-serial lock-clear-start|key=${key}|phase=${serialEntry.state.phase}`,
+      { debugOnly: true },
+      debugGate,
+    );
+    serialEntry.state.phase = 'lock_clear_start';
+    serialEntry.state.updatedAt = Date.now();
+    release();
+    serialEntry.state.phase = 'lock_clear_done';
+    serialEntry.state.updatedAt = Date.now();
+    const currentEntries = bncrConversationHistoryChains.get(key);
+    if (currentEntries) {
+      const entryIndex = currentEntries.indexOf(serialEntry);
+      if (entryIndex >= 0) currentEntries.splice(entryIndex, 1);
+      if (currentEntries.length === 0) bncrConversationHistoryChains.delete(key);
+    }
+    emitBncrLogLine(
+      'info',
+      `[bncr] conversation-history-serial lock-clear-done|key=${key}|phase=${serialEntry.state.phase}`,
+      { debugOnly: true },
+      debugGate,
+    );
+  }
+}
+
+export function clearConversationHistorySerialLocks(reason = 'runtime-restart', owner?: string) {
+  bncrConversationHistorySerialOwner =
+    owner || `${reason}:${Date.now()}:${Math.random().toString(16).slice(2, 8)}`;
+  const staleEntries = Array.from(bncrConversationHistoryChains.values()).flat();
+  const staleCount = staleEntries.length;
+  for (const entry of staleEntries) {
+    if (entry.state.phase === 'queued') {
+      // Queued work is intentionally preserved after a hot rebuild; give it
+      // the new instance owner so it is not treated as stale when it runs.
+      entry.state.owner = bncrConversationHistorySerialOwner;
+    }
+    // Upload-completed locks can safely finish snapshot cleanup before being abandoned.
+    // Locks still uploading cannot prove delivery, so their local cache is preserved.
+    if (isUploadCompletedPhase(entry.state) && entry.cleanup) {
+      try {
+        entry.cleanup();
+      } catch (err) {
+        emitBncrLogLine(
+          'warn',
+          `[bncr] conversation-history-serial stale cleanup failed|key=${entry.state.historyKey}|reason=${String(err)}`,
+        );
+      }
+    }
+    // Started locks are abandoned but remain in the chain as a barrier. A hot
+    // rebuild must not let new tasks run while the old upload still owns state;
+    // once the old task releases its lock it leaves the map and new work runs.
+    if (entry.state.phase !== 'queued') {
+      entry.state.abandoned = true;
+      entry.state.phase = 'abandoned';
+      entry.state.updatedAt = Date.now();
+    }
+  }
+  // Do not clear the chain map here. Abandoned started entries stay visible to
+  // readConversationHistorySerialHistoryKeys so shard recovery and the worker
+  // will not race them.
+  if (staleCount > 0) {
+    emitBncrLogLine(
+      'warn',
+      `[bncr] conversation-history-serial settled stale locks|count=${staleCount}|reason=${reason}`,
+    );
+  }
+  return staleCount;
+}
+
+export function readConversationHistorySerialStates(): readonly ConversationHistorySerialState[] {
+  return Array.from(bncrConversationHistoryChains.values()).flatMap((entries) =>
+    entries.map((entry) => ({
+      historyKey: entry.state.historyKey,
+      ...(entry.state.owner ? { owner: entry.state.owner } : {}),
+      phase: entry.state.phase,
+      updatedAt: entry.state.updatedAt,
+      snapshotMessageIds: [...entry.state.snapshotMessageIds],
+      ...(entry.state.cacheKey ? { cacheKey: entry.state.cacheKey } : {}),
+      uploadCompleted: entry.state.uploadCompleted,
+      abandoned: entry.state.abandoned,
+    })),
+  );
+}
+
+export function readConversationHistorySerialHistoryKeys(): string[] {
+  return Array.from(bncrConversationHistoryChains.keys()).filter(
+    (historyKey) => (bncrConversationHistoryChains.get(historyKey)?.length ?? 0) > 0,
+  );
+}
+
+export function resetConversationHistorySerialForTest() {
+  setConversationHistorySerialOwner('default');
+  clearConversationHistorySerialLocks('test');
+  // Tests must never inherit queued chains from an earlier test. Runtime
+  // restarts deliberately keep queued work in the serial chain, so only the
+  // test helper fully abandons those entries as well.
+  for (const entry of Array.from(bncrConversationHistoryChains.values()).flat()) {
+    entry.state.abandoned = true;
+    entry.state.phase = 'abandoned';
+    entry.state.updatedAt = Date.now();
+    entry.chain.catch(() => {});
+    entry.abort(new Error('conversation-history-serial test reset'));
+  }
+  bncrConversationHistoryChains.clear();
+}

package/src/messaging/inbound/conversation-history.ts

@@ -1,3 +1,4 @@
+import { createHash } from 'node:crypto';
 import {
   createChannelHistoryWindow,
   DEFAULT_GROUP_HISTORY_LIMIT as DEFAULT_HISTORY_LIMIT,
@@ -17,12 +18,75 @@ export type BncrConversationHistoryMap = Map<string, BncrHistoryEntry[]>;
 
 type BncrHistoryMediaKind = NonNullable<HistoryMediaEntry['kind']>;
 
+const conversationHistoryVersions = new WeakMap<BncrConversationHistoryMap, Map<string, number>>();
+
+function buildSyntheticHistoryMessageId(seed: string): string {
+  const digest = createHash('sha1').update(seed).digest('hex').slice(0, 24);
+  return `bncr-synthetic:${digest}`;
+}
+
+export function buildBncrBotReplyMessageId(args: {
+  historyKey: string;
+  sender: string;
+  senderId?: string;
+  body: string;
+  timestamp?: number;
+  messageId?: string;
+  media?: HistoryMediaEntry[];
+}): string {
+  const provided = String(args.messageId || '').trim();
+  if (provided) return provided;
+  return buildSyntheticHistoryMessageId(
+    JSON.stringify({
+      historyKey: args.historyKey,
+      sender: args.sender,
+      senderId: args.senderId,
+      body: args.body,
+      timestamp: args.timestamp,
+      media: args.media?.map((item) => [item.path, item.contentType, item.kind, item.messageId]),
+    }),
+  );
+}
+
+function bumpConversationHistoryVersion(
+  historyMap: BncrConversationHistoryMap,
+  historyKey: string,
+): number {
+  let versions = conversationHistoryVersions.get(historyMap);
+  if (!versions) {
+    versions = new Map();
+    conversationHistoryVersions.set(historyMap, versions);
+  }
+  const next = (versions.get(historyKey) || 0) + 1;
+  versions.set(historyKey, next);
+  return next;
+}
+
+export function readConversationHistoryVersion(
+  historyMap: BncrConversationHistoryMap,
+  historyKey: string,
+): number {
+  return conversationHistoryVersions.get(historyMap)?.get(historyKey) ?? 0;
+}
+
+export function resetConversationHistoryVersions(historyMap: BncrConversationHistoryMap): void {
+  conversationHistoryVersions.delete(historyMap);
+}
+
 function normalizeTextBody(value: string): string {
   return String(value || '')
     .replace(/\s+/g, ' ')
     .trim();
 }
 
+export function resolveBncrHistoryLimit(historyLimit?: number): number {
+  if (typeof historyLimit !== 'number' || !Number.isFinite(historyLimit)) {
+    return DEFAULT_HISTORY_LIMIT;
+  }
+  const resolved = Math.floor(historyLimit);
+  return resolved >= 2 ? resolved : DEFAULT_HISTORY_LIMIT;
+}
+
 export function buildBncrConversationHistoryKey(parsed: ParsedInbound): string | null {
   const platform = String(parsed.platform || '').trim();
   if (!platform) return null;
@@ -50,6 +114,11 @@ export function buildBncrConversationHistoryKeyFromRoute(args: {
   return null;
 }
 
+export function resolveBncrConversationHistoryMessageId(parsed: ParsedInbound): string | undefined {
+  const msgId = String(parsed.msgId || '').trim();
+  return msgId || undefined;
+}
+
 export function recordBncrPendingConversationText(args: {
   historyMap: BncrConversationHistoryMap;
   parsed: ParsedInbound;
@@ -58,19 +127,14 @@ export function recordBncrPendingConversationText(args: {
   bodyText: string;
   historyLimit?: number;
 }) {
-  const limit =
-    typeof args.historyLimit === 'number' &&
-    Number.isFinite(args.historyLimit) &&
-    args.historyLimit >= 0
-      ? Math.floor(args.historyLimit)
-      : DEFAULT_HISTORY_LIMIT;
+  const limit = resolveBncrHistoryLimit(args.historyLimit);
   const historyKey = buildBncrConversationHistoryKey(args.parsed);
   const body = normalizeTextBody(args.bodyText);
   if (!historyKey || !body || args.parsed.msgType !== 'text') return;
-  const msgId = String(args.parsed.msgId || '').trim();
-  if (msgId) {
+  const messageId = resolveBncrConversationHistoryMessageId(args.parsed);
+  if (messageId) {
     const existing = args.historyMap.get(historyKey) || [];
-    if (existing.some((e) => e.messageId === msgId)) return;
+    if (existing.some((e) => e.messageId === messageId)) return;
   }
   createChannelHistoryWindow({ historyMap: args.historyMap }).record({
     historyKey,
@@ -80,10 +144,11 @@ export function recordBncrPendingConversationText(args: {
       senderId: args.senderId,
       body,
       timestamp: Date.now(),
-      messageId: args.parsed.msgId,
+      ...(messageId ? { messageId } : {}),
       role: 'user',
     },
   });
+  bumpConversationHistoryVersion(args.historyMap, historyKey);
 }
 
 function inferBncrHistoryMediaKind(args: {
@@ -109,7 +174,7 @@ function buildBncrHistoryMediaBody(kind: BncrHistoryMediaKind): string {
   return `<media:${kind}>`;
 }
 
-export async function recordBncrPendingConversationMedia(args: {
+export function recordBncrPendingConversationMedia(args: {
   historyMap: BncrConversationHistoryMap;
   parsed: ParsedInbound;
   senderDisplayName: string;
@@ -123,12 +188,7 @@ export async function recordBncrPendingConversationMedia(args: {
   mediaContentType?: string;
   historyLimit?: number;
 }) {
-  const limit =
-    typeof args.historyLimit === 'number' &&
-    Number.isFinite(args.historyLimit) &&
-    args.historyLimit >= 0
-      ? Math.floor(args.historyLimit)
-      : DEFAULT_HISTORY_LIMIT;
+  const limit = resolveBncrHistoryLimit(args.historyLimit);
   const historyKey = buildBncrConversationHistoryKey(args.parsed);
   if (!historyKey || args.parsed.msgType === 'text') return;
   const normalizedMediaItems = Array.isArray(args.mediaItems) ? args.mediaItems : [];
@@ -149,10 +209,10 @@ export async function recordBncrPendingConversationMedia(args: {
       });
   const body = normalizeTextBody(args.bodyText) || buildBncrHistoryMediaBody(kind);
   if (normalizedMediaItems.length === 0) {
-    const msgId = String(args.parsed.msgId || '').trim();
-    if (msgId) {
+    const messageId = resolveBncrConversationHistoryMessageId(args.parsed);
+    if (messageId) {
       const existing = args.historyMap.get(historyKey) || [];
-      if (existing.some((e) => e.messageId === msgId)) return;
+      if (existing.some((e) => e.messageId === messageId)) return;
     }
     createChannelHistoryWindow({ historyMap: args.historyMap }).record({
       historyKey,
@@ -162,16 +222,17 @@ export async function recordBncrPendingConversationMedia(args: {
         senderId: args.senderId,
         body,
         timestamp: Date.now(),
-        messageId: args.parsed.msgId,
+        ...(messageId ? { messageId } : {}),
         role: 'user',
       },
     });
+    bumpConversationHistoryVersion(args.historyMap, historyKey);
     return;
   }
-  const msgId = String(args.parsed.msgId || '').trim();
-  if (msgId) {
+  const messageId = resolveBncrConversationHistoryMessageId(args.parsed);
+  if (messageId) {
     const existing = args.historyMap.get(historyKey) || [];
-    if (existing.some((e) => e.messageId === msgId)) return;
+    if (existing.some((e) => e.messageId === messageId)) return;
   }
   createChannelHistoryWindow({ historyMap: args.historyMap }).record({
     historyKey,
@@ -181,7 +242,7 @@ export async function recordBncrPendingConversationMedia(args: {
       senderId: args.senderId,
       body,
       timestamp: Date.now(),
-      messageId: args.parsed.msgId,
+      ...(messageId ? { messageId } : {}),
       role: 'user',
       media: normalizedMediaItems.map(
         (item) =>
@@ -189,11 +250,12 @@ export async function recordBncrPendingConversationMedia(args: {
             path: item.path,
             contentType: item.contentType || args.mediaContentType,
             kind: item.kind || kind,
-            messageId: args.parsed.msgId,
+            messageId,
           }) satisfies HistoryMediaEntry,
       ),
     },
   });
+  bumpConversationHistoryVersion(args.historyMap, historyKey);
 }
 
 export function recordBncrBotReply(args: {
@@ -206,20 +268,21 @@ export function recordBncrBotReply(args: {
   messageId?: string;
   media?: HistoryMediaEntry[];
   historyLimit?: number;
-}) {
-  const limit =
-    typeof args.historyLimit === 'number' &&
-    Number.isFinite(args.historyLimit) &&
-    args.historyLimit >= 0
-      ? Math.floor(args.historyLimit)
-      : DEFAULT_HISTORY_LIMIT;
+}): boolean {
+  const limit = resolveBncrHistoryLimit(args.historyLimit);
   const body = normalizeTextBody(args.body);
-  if (!body) return;
-  const msgId = String(args.messageId || '').trim();
-  if (msgId) {
-    const existing = args.historyMap.get(args.historyKey) || [];
-    if (existing.some((e) => e.messageId === msgId)) return;
-  }
+  if (!body) return false;
+  const msgId = buildBncrBotReplyMessageId({
+    historyKey: args.historyKey,
+    sender: args.sender,
+    senderId: args.senderId,
+    body,
+    timestamp: args.timestamp,
+    messageId: args.messageId,
+    media: args.media,
+  });
+  const existing = args.historyMap.get(args.historyKey) || [];
+  if (existing.some((e) => e.messageId === msgId)) return false;
   createChannelHistoryWindow({ historyMap: args.historyMap }).record({
     historyKey: args.historyKey,
     limit,
@@ -228,11 +291,22 @@ export function recordBncrBotReply(args: {
       ...(args.senderId ? { senderId: args.senderId } : {}),
       body,
       timestamp: args.timestamp ?? Date.now(),
-      ...(args.messageId ? { messageId: args.messageId } : {}),
+      messageId: msgId,
       role: 'assistant',
-      ...(Array.isArray(args.media) && args.media.length > 0 ? { media: args.media } : {}),
+      ...(Array.isArray(args.media) && args.media.length > 0
+        ? {
+            media: args.media.map((item) => ({
+              ...(item?.path ? { path: item.path } : {}),
+              ...(item?.contentType ? { contentType: item.contentType } : {}),
+              ...(item?.kind ? { kind: item.kind } : {}),
+              messageId: item?.messageId || msgId,
+            })),
+          }
+        : {}),
     },
   });
+  bumpConversationHistoryVersion(args.historyMap, args.historyKey);
+  return true;
 }
 
 function cloneBncrHistoryEntry(entry: BncrHistoryEntry): BncrHistoryEntry {
@@ -261,16 +335,41 @@ export function readBncrPendingConversationHistorySnapshot(args: {
   parsed: ParsedInbound;
   historyLimit?: number;
 }): BncrHistoryEntry[] {
-  const limit =
-    typeof args.historyLimit === 'number' &&
-    Number.isFinite(args.historyLimit) &&
-    args.historyLimit >= 0
-      ? Math.floor(args.historyLimit)
-      : DEFAULT_HISTORY_LIMIT;
+  const limit = resolveBncrHistoryLimit(args.historyLimit);
   const historyKey = buildBncrConversationHistoryKey(args.parsed);
   if (!historyKey) return [];
-  const entries = args.historyMap.get(historyKey) || [];
-  if (entries.length === 0) return [];
+  const rawEntries = args.historyMap.get(historyKey) || [];
+  if (rawEntries.length === 0) return [];
+  let normalized = false;
+  const entries = rawEntries.map((entry, entryIndex) => {
+    const messageId =
+      String(entry.messageId || '').trim() ||
+      buildSyntheticHistoryMessageId(
+        JSON.stringify({
+          historyKey,
+          entryIndex,
+          sender: entry.sender,
+          senderId: entry.senderId,
+          body: entry.body,
+          timestamp: entry.timestamp,
+        }),
+      );
+    if (messageId === entry.messageId) return entry;
+    normalized = true;
+    return {
+      ...entry,
+      messageId,
+      ...(Array.isArray(entry.media)
+        ? {
+            media: entry.media.map((item) => ({
+              ...item,
+              messageId: item.messageId || messageId,
+            })),
+          }
+        : {}),
+    };
+  });
+  if (normalized) args.historyMap.set(historyKey, entries);
   return entries
     .slice()
     .sort((a, b) => (a.timestamp ?? 0) - (b.timestamp ?? 0))
@@ -316,16 +415,36 @@ export function clearBncrPendingConversationHistory(args: {
   parsed: ParsedInbound;
   historyLimit?: number;
 }) {
-  const limit =
-    typeof args.historyLimit === 'number' &&
-    Number.isFinite(args.historyLimit) &&
-    args.historyLimit >= 0
-      ? Math.floor(args.historyLimit)
-      : DEFAULT_HISTORY_LIMIT;
+  const limit = resolveBncrHistoryLimit(args.historyLimit);
   const historyKey = buildBncrConversationHistoryKey(args.parsed);
   if (!historyKey) return;
   createChannelHistoryWindow({ historyMap: args.historyMap }).clear({
     historyKey,
     limit: limit,
   });
+  bumpConversationHistoryVersion(args.historyMap, historyKey);
+}
+
+export function removeBncrConversationHistoryMessageIds(args: {
+  historyMap: BncrConversationHistoryMap;
+  historyKey: string;
+  messageIds: ReadonlyArray<string | undefined | null>;
+}): number {
+  const messageIds = new Set(
+    args.messageIds
+      .map((messageId) => String(messageId || '').trim())
+      .filter((messageId) => Boolean(messageId)),
+  );
+  if (messageIds.size === 0) return 0;
+  const current = args.historyMap.get(args.historyKey) || [];
+  if (current.length === 0) return 0;
+  const next = current.filter(
+    (entry) =>
+      !String(entry.messageId || '').trim() || !messageIds.has(String(entry.messageId).trim()),
+  );
+  if (next.length === current.length) return 0;
+  args.historyMap.set(args.historyKey, next);
+  // Snapshot cleanup must not invalidate flushes queued from replies written
+  // while the earlier snapshot was uploading.
+  return current.length - next.length;
 }