vellum 0.2.13 → 0.2.14

package/src/memory/conflict-policy.ts

@@ -0,0 +1,73 @@
+/**
+ * Pure, deterministic policy helpers for memory conflict eligibility.
+ * Used by contradiction checker, session conflict gate, and background resolver.
+ */
+
+export interface ConflictPolicyConfig {
+  conflictableKinds: readonly string[];
+  [key: string]: unknown;
+}
+
+/**
+ * Returns true when the given memory item kind is eligible to participate
+ * in conflict detection according to the current policy.
+ */
+export function isConflictKindEligible(kind: string, config: ConflictPolicyConfig): boolean {
+  return config.conflictableKinds.includes(kind);
+}
+
+/**
+ * Returns true when both sides of a potential conflict pair are kind-eligible.
+ */
+export function isConflictKindPairEligible(
+  existingKind: string,
+  candidateKind: string,
+  config: ConflictPolicyConfig,
+): boolean {
+  return isConflictKindEligible(existingKind, config) && isConflictKindEligible(candidateKind, config);
+}
+
+// ── Transient statement classification ─────────────────────────────────
+
+const PR_URL_PATTERN = /github\.com\/[^/]+\/[^/]+\/pull\/\d+/i;
+const ISSUE_TICKET_PATTERN = /\b(?:issue|pr|ticket|pull request)\s*#?\d+/i;
+const TRACKING_LANGUAGE_PATTERN = /\b(?:this pr|that issue|while we wait|currently tracking)\b/i;
+
+/**
+ * Returns true when a statement looks like a transient tracking note
+ * (PR URLs, issue references, short-lived progress notes) rather than
+ * a durable user preference or instruction.
+ */
+export function isTransientTrackingStatement(statement: string): boolean {
+  if (PR_URL_PATTERN.test(statement)) return true;
+  if (ISSUE_TICKET_PATTERN.test(statement)) return true;
+  if (TRACKING_LANGUAGE_PATTERN.test(statement)) return true;
+  return false;
+}
+
+const DURABLE_INSTRUCTION_CUES = /\b(?:always|never|default|every time|by default|style|format|tone|convention|standard)\b/i;
+
+/**
+ * Returns true when a statement contains strong durable instruction cues,
+ * suggesting it represents a persistent user preference or style rule.
+ */
+export function isDurableInstructionStatement(statement: string): boolean {
+  return DURABLE_INSTRUCTION_CUES.test(statement);
+}
+
+/**
+ * Returns true when a statement of the given kind is eligible to participate
+ * in conflict detection at the statement level. This combines kind eligibility
+ * with statement-level durability heuristics.
+ *
+ * For instruction/style kinds: requires positive durable cues and no transient cues.
+ * For other eligible kinds: rejects if transient tracking cues dominate.
+ */
+export function isStatementConflictEligible(kind: string, statement: string, config?: ConflictPolicyConfig): boolean {
+  if (config && !isConflictKindEligible(kind, config)) return false;
+  if (isTransientTrackingStatement(statement)) return false;
+  if (kind === 'instruction' || kind === 'style') {
+    return isDurableInstructionStatement(statement);
+  }
+  return true;
+}

package/src/memory/conflict-store.ts

@@ -50,6 +50,8 @@ export interface ResolveConflictInput {
 export interface PendingConflictDetail extends MemoryItemConflict {
   existingStatement: string;
   candidateStatement: string;
+  existingKind: string;
+  candidateKind: string;
 }
 
 export type ConflictResolutionAction = 'keep_existing' | 'keep_candidate' | 'merge';
@@ -170,7 +172,9 @@ export function listPendingConflictDetails(scopeId: string, limit = 100): Pendin
       c.created_at,
       c.updated_at,
       existing_item.statement AS existing_statement,
-      candidate_item.statement AS candidate_statement
+      candidate_item.statement AS candidate_statement,
+      existing_item.kind AS existing_kind,
+      candidate_item.kind AS candidate_kind
     FROM memory_item_conflicts c
     INNER JOIN memory_items existing_item ON existing_item.id = c.existing_item_id
     INNER JOIN memory_items candidate_item ON candidate_item.id = c.candidate_item_id
@@ -193,6 +197,8 @@ export function listPendingConflictDetails(scopeId: string, limit = 100): Pendin
     updated_at: number;
     existing_statement: string;
     candidate_statement: string;
+    existing_kind: string;
+    candidate_kind: string;
   }>;
 
   return rows.map((row) => ({
@@ -210,6 +216,8 @@ export function listPendingConflictDetails(scopeId: string, limit = 100): Pendin
     updatedAt: row.updated_at,
     existingStatement: row.existing_statement,
     candidateStatement: row.candidate_statement,
+    existingKind: row.existing_kind,
+    candidateKind: row.candidate_kind,
   }));
 }
 

package/src/memory/contradiction-checker.ts

@@ -3,6 +3,8 @@ import { eq } from 'drizzle-orm';
 import { getConfig } from '../config/loader.js';
 import { getLogger } from '../util/logger.js';
 import { truncate } from '../util/truncate.js';
+import { areStatementsCoherent } from './conflict-intent.js';
+import { isConflictKindEligible, isStatementConflictEligible } from './conflict-policy.js';
 import { createOrUpdatePendingConflict } from './conflict-store.js';
 import { getDb } from './db.js';
 import { enqueueMemoryJob } from './jobs-store.js';
@@ -61,7 +63,33 @@ export async function checkContradictions(newItemId: string): Promise<void> {
     return;
   }
 
+  if (!isConflictKindEligible(newItem.kind, config.memory.conflicts)) {
+    log.debug({ newItemId, kind: newItem.kind }, 'Skipping contradiction check — kind not eligible for conflicts');
+    return;
+  }
+
+  // Skip if the new item's statement is transient/non-durable
+  if (!isStatementConflictEligible(newItem.kind, newItem.statement, config.memory.conflicts)) {
+    log.debug({ newItemId, kind: newItem.kind }, 'Skipping contradiction check — statement is transient or non-durable');
+    return;
+  }
+
   for (const existing of candidates) {
+    // Skip candidate if its statement is transient/non-durable
+    if (!isStatementConflictEligible(existing.kind, existing.statement, config.memory.conflicts)) {
+      log.debug({ existingId: existing.id }, 'Skipping candidate — statement is transient or non-durable');
+      continue;
+    }
+
+    // Skip pairs with zero topical overlap — they are not real contradictions
+    if (!areStatementsCoherent(existing.statement, newItem.statement)) {
+      log.debug(
+        { existingId: existing.id, newId: newItem.id },
+        'Skipping candidate — zero statement overlap (incoherent pair)',
+      );
+      continue;
+    }
+
     try {
       const result = await classifyRelationship(apiKey, existing, newItem);
       await handleRelationship(result, existing, newItem);

package/src/memory/conversation-key-store.ts

@@ -52,6 +52,21 @@ export function deleteConversationKey(
     .run();
 }
 
+/**
+ * Map a conversation key to an existing conversation ID (no creation).
+ */
+export function setConversationKey(conversationKey: string, conversationId: string): void {
+  const db = getDb();
+  db.insert(conversationKeys)
+    .values({
+      id: uuid(),
+      conversationKey,
+      conversationId,
+      createdAt: Date.now(),
+    })
+    .run();
+}
+
 /**
  * Get or create a conversation for the given conversationKey.
  *

package/src/memory/db.ts

@@ -790,6 +790,10 @@ export function initializeDb(): void {
   // Add claim ownership token to prevent cross-handler claim interference
   try { database.run(/*sql*/ `ALTER TABLE processed_callbacks ADD COLUMN claim_id TEXT`); } catch { /* already exists */ }
 
+  // Caller identity persistence for auditability
+  try { database.run(/*sql*/ `ALTER TABLE call_sessions ADD COLUMN caller_identity_mode TEXT`); } catch { /* already exists */ }
+  try { database.run(/*sql*/ `ALTER TABLE call_sessions ADD COLUMN caller_identity_source TEXT`); } catch { /* already exists */ }
+
   // Unique constraint: at most one non-null provider_call_sid per (provider, provider_call_sid).
   // On upgraded databases that pre-date this constraint, duplicate rows may exist; deduplicate
   // them first to avoid a UNIQUE constraint failure that would prevent startup.
@@ -900,6 +904,28 @@ export function initializeDb(): void {
   database.run(/*sql*/ `CREATE INDEX IF NOT EXISTS idx_task_runs_status ON task_runs(status)`);
   database.run(/*sql*/ `CREATE INDEX IF NOT EXISTS idx_task_candidates_promoted ON task_candidates(promoted_task_id)`);
 
+  // ── External Conversation Bindings ──────────────────────────────────
+
+  database.run(/*sql*/ `
+    CREATE TABLE IF NOT EXISTS external_conversation_bindings (
+      conversation_id TEXT PRIMARY KEY REFERENCES conversations(id) ON DELETE CASCADE,
+      source_channel TEXT NOT NULL,
+      external_chat_id TEXT NOT NULL,
+      external_user_id TEXT,
+      display_name TEXT,
+      username TEXT,
+      created_at INTEGER NOT NULL,
+      updated_at INTEGER NOT NULL,
+      last_inbound_at INTEGER,
+      last_outbound_at INTEGER
+    )
+  `);
+
+  database.run(/*sql*/ `CREATE INDEX IF NOT EXISTS idx_ext_conv_bindings_channel_chat ON external_conversation_bindings(source_channel, external_chat_id)`);
+  database.run(/*sql*/ `CREATE INDEX IF NOT EXISTS idx_ext_conv_bindings_channel ON external_conversation_bindings(source_channel)`);
+
+  migrateExtConvBindingsChannelChatUnique(database);
+
   migrateMemoryFtsBackfill(database);
 }
 
@@ -1764,6 +1790,61 @@ function migrateLlmUsageEventsDropAssistantId(database: ReturnType<typeof drizzl
   }
 }
 
+/**
+ * One-shot migration: deduplicate external_conversation_bindings rows that
+ * share the same (source_channel, external_chat_id), then create a unique
+ * index to enforce the invariant at DB level.
+ *
+ * For each duplicate group, the binding with the newest updatedAt (then
+ * createdAt) is kept; older duplicates are deleted.
+ */
+function migrateExtConvBindingsChannelChatUnique(database: ReturnType<typeof drizzle<typeof schema>>): void {
+  const raw = (database as unknown as { $client: Database }).$client;
+
+  // If the unique index already exists, nothing to do.
+  const idxExists = raw.query(
+    `SELECT 1 FROM sqlite_master WHERE type = 'index' AND name = 'idx_ext_conv_bindings_channel_chat_unique'`,
+  ).get();
+  if (idxExists) return;
+
+  // Check if the table exists (first boot edge case).
+  const tableExists = raw.query(
+    `SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = 'external_conversation_bindings'`,
+  ).get();
+  if (!tableExists) return;
+
+  // Remove duplicates: keep the row with the newest updatedAt, then createdAt.
+  // Since conversation_id is the PK (rowid alias), we use it for ordering ties.
+  try {
+    raw.exec('BEGIN');
+
+    raw.exec(/*sql*/ `
+      DELETE FROM external_conversation_bindings
+      WHERE rowid NOT IN (
+        SELECT rowid FROM (
+          SELECT rowid,
+                 ROW_NUMBER() OVER (
+                   PARTITION BY source_channel, external_chat_id
+                   ORDER BY updated_at DESC, created_at DESC, rowid DESC
+                 ) AS rn
+          FROM external_conversation_bindings
+        )
+        WHERE rn = 1
+      )
+    `);
+
+    raw.exec(/*sql*/ `
+      CREATE UNIQUE INDEX IF NOT EXISTS idx_ext_conv_bindings_channel_chat_unique
+      ON external_conversation_bindings(source_channel, external_chat_id)
+    `);
+
+    raw.exec('COMMIT');
+  } catch (e) {
+    try { raw.exec('ROLLBACK'); } catch { /* no active transaction */ }
+    throw e;
+  }
+}
+
 /**
  * One-shot migration: remove duplicate (provider, provider_call_sid) rows from
  * call_sessions so that the unique index can be created safely on upgraded databases

package/src/memory/embedding-local.ts

@@ -1,5 +1,6 @@
 import type { EmbeddingBackend, EmbeddingRequestOptions } from './embedding-backend.js';
 import { getLogger } from '../util/logger.js';
+import { PromiseGuard } from '../util/promise-guard.js';
 
 const log = getLogger('memory-embedding-local');
 
@@ -19,7 +20,7 @@ export class LocalEmbeddingBackend implements EmbeddingBackend {
   readonly provider = 'local' as const;
   readonly model: string;
   private extractor: FeatureExtractionPipeline | null = null;
-  private initPromise: Promise<void> | null = null;
+  private readonly initGuard = new PromiseGuard<void>();
 
   constructor(model: string) {
     this.model = model;
@@ -50,18 +51,7 @@ export class LocalEmbeddingBackend implements EmbeddingBackend {
 
   private async ensureInitialized(): Promise<void> {
     if (this.extractor) return;
-    if (this.initPromise) {
-      await this.initPromise;
-      return;
-    }
-
-    this.initPromise = this.initialize();
-    try {
-      await this.initPromise;
-    } catch (err) {
-      this.initPromise = null;
-      throw err;
-    }
+    await this.initGuard.run(() => this.initialize());
   }
 
   private async initialize(): Promise<void> {

package/src/memory/external-conversation-store.ts

@@ -0,0 +1,234 @@
+/**
+ * Store for external conversation bindings — maps internal conversation IDs
+ * to external channel identifiers (e.g. Telegram chat ID, SMS thread ID).
+ *
+ * This enables the system to track which conversations originated from
+ * external channels and expose channel metadata in session/conversation
+ * list APIs.
+ */
+
+import { eq, and, inArray } from 'drizzle-orm';
+import { getDb } from './db.js';
+import { externalConversationBindings } from './schema.js';
+
+export interface ExternalConversationBinding {
+  conversationId: string;
+  sourceChannel: string;
+  externalChatId: string;
+  externalUserId?: string | null;
+  displayName?: string | null;
+  username?: string | null;
+  createdAt: number;
+  updatedAt: number;
+  lastInboundAt?: number | null;
+  lastOutboundAt?: number | null;
+}
+
+export interface UpsertBindingInput {
+  conversationId: string;
+  sourceChannel: string;
+  externalChatId: string;
+  externalUserId?: string | null;
+  displayName?: string | null;
+  username?: string | null;
+}
+
+/**
+ * Insert or update an external conversation binding on conflict (conversationId).
+ * On conflict, updates channel metadata and timestamps.
+ */
+export function upsertBinding(input: UpsertBindingInput): void {
+  const db = getDb();
+  const now = Date.now();
+
+  // If a stale binding exists for this (sourceChannel, externalChatId) under a
+  // different conversationId, remove it first so the unique index is not violated.
+  const existing = getBindingByChannelChat(input.sourceChannel, input.externalChatId);
+  if (existing && existing.conversationId !== input.conversationId) {
+    db.delete(externalConversationBindings)
+      .where(eq(externalConversationBindings.conversationId, existing.conversationId))
+      .run();
+  }
+
+  db.insert(externalConversationBindings)
+    .values({
+      conversationId: input.conversationId,
+      sourceChannel: input.sourceChannel,
+      externalChatId: input.externalChatId,
+      externalUserId: input.externalUserId ?? null,
+      displayName: input.displayName ?? null,
+      username: input.username ?? null,
+      createdAt: now,
+      updatedAt: now,
+      lastInboundAt: now,
+    })
+    .onConflictDoUpdate({
+      target: externalConversationBindings.conversationId,
+      set: {
+        sourceChannel: input.sourceChannel,
+        externalChatId: input.externalChatId,
+        externalUserId: input.externalUserId ?? null,
+        displayName: input.displayName ?? null,
+        username: input.username ?? null,
+        updatedAt: now,
+        lastInboundAt: now,
+      },
+    })
+    .run();
+}
+
+/**
+ * Upsert an external conversation binding for outbound sends.
+ * Similar to upsertBinding but touches lastOutboundAt instead of lastInboundAt,
+ * and only requires channel identifiers (no sender metadata needed).
+ */
+export function upsertOutboundBinding(input: {
+  conversationId: string;
+  sourceChannel: string;
+  externalChatId: string;
+}): void {
+  const db = getDb();
+  const now = Date.now();
+
+  // If a stale binding exists for this (sourceChannel, externalChatId) under a
+  // different conversationId, remove it first so the unique index is not violated.
+  const existing = getBindingByChannelChat(input.sourceChannel, input.externalChatId);
+  if (existing && existing.conversationId !== input.conversationId) {
+    db.delete(externalConversationBindings)
+      .where(eq(externalConversationBindings.conversationId, existing.conversationId))
+      .run();
+  }
+
+  db.insert(externalConversationBindings)
+    .values({
+      conversationId: input.conversationId,
+      sourceChannel: input.sourceChannel,
+      externalChatId: input.externalChatId,
+      externalUserId: null,
+      displayName: null,
+      username: null,
+      createdAt: now,
+      updatedAt: now,
+      lastOutboundAt: now,
+    })
+    .onConflictDoUpdate({
+      target: externalConversationBindings.conversationId,
+      set: {
+        sourceChannel: input.sourceChannel,
+        externalChatId: input.externalChatId,
+        updatedAt: now,
+        lastOutboundAt: now,
+      },
+    })
+    .run();
+}
+
+/**
+ * Look up an external binding by conversation ID.
+ */
+export function getBindingByConversation(
+  conversationId: string,
+): ExternalConversationBinding | null {
+  const db = getDb();
+  const row = db
+    .select()
+    .from(externalConversationBindings)
+    .where(eq(externalConversationBindings.conversationId, conversationId))
+    .get();
+  return row ?? null;
+}
+
+/**
+ * Look up an external binding by channel + external chat ID.
+ */
+export function getBindingByChannelChat(
+  sourceChannel: string,
+  externalChatId: string,
+): ExternalConversationBinding | null {
+  const db = getDb();
+  const row = db
+    .select()
+    .from(externalConversationBindings)
+    .where(
+      and(
+        eq(externalConversationBindings.sourceChannel, sourceChannel),
+        eq(externalConversationBindings.externalChatId, externalChatId),
+      ),
+    )
+    .get();
+  return row ?? null;
+}
+
+/**
+ * Remove an external binding for a conversation.
+ */
+export function deleteBinding(conversationId: string): void {
+  const db = getDb();
+  db.delete(externalConversationBindings)
+    .where(eq(externalConversationBindings.conversationId, conversationId))
+    .run();
+}
+
+/**
+ * Remove an external binding by channel + external chat ID.
+ * Used when disconnecting a synced thread by its channel identifiers.
+ */
+export function deleteBindingByChannelChat(
+  sourceChannel: string,
+  externalChatId: string,
+): void {
+  const db = getDb();
+  db.delete(externalConversationBindings)
+    .where(
+      and(
+        eq(externalConversationBindings.sourceChannel, sourceChannel),
+        eq(externalConversationBindings.externalChatId, externalChatId),
+      ),
+    )
+    .run();
+}
+
+/**
+ * List all external bindings, optionally filtered by sourceChannel.
+ */
+export function listBindings(options?: {
+  sourceChannel?: string;
+}): ExternalConversationBinding[] {
+  const db = getDb();
+  const query = db
+    .select()
+    .from(externalConversationBindings);
+
+  if (options?.sourceChannel) {
+    return query
+      .where(eq(externalConversationBindings.sourceChannel, options.sourceChannel))
+      .all();
+  }
+
+  return query.all();
+}
+
+/**
+ * Get bindings for multiple conversation IDs at once.
+ * Returns a map of conversationId -> binding for efficient lookup.
+ */
+export function getBindingsForConversations(
+  conversationIds: string[],
+): Map<string, ExternalConversationBinding> {
+  if (conversationIds.length === 0) return new Map();
+
+  const db = getDb();
+  const result = new Map<string, ExternalConversationBinding>();
+
+  const all = db
+    .select()
+    .from(externalConversationBindings)
+    .where(inArray(externalConversationBindings.conversationId, conversationIds))
+    .all();
+
+  for (const row of all) {
+    result.set(row.conversationId, row);
+  }
+
+  return result;
+}

package/src/memory/job-handlers/conflict.ts

@@ -6,9 +6,10 @@ import {
   looksLikeClarificationReply,
   shouldAttemptConflictResolution,
 } from '../conflict-intent.js';
+import { isConflictKindPairEligible, isStatementConflictEligible } from '../conflict-policy.js';
 import { getDb } from '../db.js';
 import { resolveConflictClarification } from '../clarification-resolver.js';
-import { applyConflictResolution, listPendingConflictDetails } from '../conflict-store.js';
+import { applyConflictResolution, listPendingConflictDetails, resolveConflict } from '../conflict-store.js';
 import { enqueueMemoryJob, type MemoryJob } from '../jobs-store.js';
 import { asPositiveMs, asString } from '../job-utils.js';
 import { extractTextFromStoredMessageContent } from '../message-content.js';
@@ -43,7 +44,26 @@ export async function resolvePendingConflictsForMessageJob(job: MemoryJob, confi
   if (!clarificationReply) return;
 
   const pending = listPendingConflictDetails(scopeId, 25);
-  const eligible = pending.filter((conflict) => conflict.createdAt <= message.createdAt);
+
+  // Dismiss non-actionable conflicts (kind or statement policy)
+  const conflictableKinds = config.memory.conflicts.conflictableKinds;
+  for (const conflict of pending) {
+    const kindEligible = isConflictKindPairEligible(
+      conflict.existingKind, conflict.candidateKind, { conflictableKinds },
+    );
+    if (!kindEligible
+      || !isStatementConflictEligible(conflict.existingKind, conflict.existingStatement, { conflictableKinds })
+      || !isStatementConflictEligible(conflict.candidateKind, conflict.candidateStatement, { conflictableKinds })) {
+      resolveConflict(conflict.id, {
+        status: 'dismissed',
+        resolutionNote: 'Dismissed by conflict policy (transient/non-durable).',
+      });
+    }
+  }
+
+  // Re-fetch after dismissal
+  const actionablePending = listPendingConflictDetails(scopeId, 25);
+  const eligible = actionablePending.filter((conflict) => conflict.createdAt <= message.createdAt);
   if (eligible.length === 0) return;
   const candidates = eligible.filter((conflict) => {
     const askedAt = conflict.lastAskedAt;