@vellumai/assistant 0.3.4 → 0.3.6

package/src/memory/schema.ts

@@ -1,4 +1,4 @@
-import { sqliteTable, text, integer, real, blob } from 'drizzle-orm/sqlite-core';
+import { sqliteTable, text, integer, real, blob, index } from 'drizzle-orm/sqlite-core';
 
 export const conversations = sqliteTable('conversations', {
   id: text('id').primaryKey(),
@@ -12,7 +12,9 @@ export const conversations = sqliteTable('conversations', {
   contextCompactedMessageCount: integer('context_compacted_message_count').notNull().default(0),
   contextCompactedAt: integer('context_compacted_at'),
   threadType: text('thread_type').notNull().default('standard'),
+  source: text('source').notNull().default('user'),
   memoryScopeId: text('memory_scope_id').notNull().default('default'),
+  originChannel: text('origin_channel'),
 });
 
 export const messages = sqliteTable('messages', {
@@ -24,7 +26,9 @@ export const messages = sqliteTable('messages', {
   content: text('content').notNull(),
   createdAt: integer('created_at').notNull(),
   metadata: text('metadata'),
-});
+}, (table) => [
+  index('idx_messages_conversation_id').on(table.conversationId),
+]);
 
 export const toolInvocations = sqliteTable('tool_invocations', {
   id: text('id').primaryKey(),
@@ -38,7 +42,9 @@ export const toolInvocations = sqliteTable('tool_invocations', {
   riskLevel: text('risk_level').notNull(),
   durationMs: integer('duration_ms').notNull(),
   createdAt: integer('created_at').notNull(),
-});
+}, (table) => [
+  index('idx_tool_invocations_conversation_id').on(table.conversationId),
+]);
 
 export const memorySegments = sqliteTable('memory_segments', {
   id: text('id').primaryKey(),
@@ -56,7 +62,10 @@ export const memorySegments = sqliteTable('memory_segments', {
   contentHash: text('content_hash'),
   createdAt: integer('created_at').notNull(),
   updatedAt: integer('updated_at').notNull(),
-});
+}, (table) => [
+  index('idx_memory_segments_scope_id').on(table.scopeId),
+  index('idx_memory_segments_conversation_id').on(table.conversationId),
+]);
 
 export const memoryItems = sqliteTable('memory_items', {
   id: text('id').primaryKey(),
@@ -75,7 +84,10 @@ export const memoryItems = sqliteTable('memory_items', {
   lastUsedAt: integer('last_used_at'),
   validFrom: integer('valid_from'),
   invalidAt: integer('invalid_at'),
-});
+}, (table) => [
+  index('idx_memory_items_scope_id').on(table.scopeId),
+  index('idx_memory_items_fingerprint').on(table.fingerprint),
+]);
 
 export const memoryItemSources = sqliteTable('memory_item_sources', {
   memoryItemId: text('memory_item_id')
@@ -105,7 +117,9 @@ export const memoryItemConflicts = sqliteTable('memory_item_conflicts', {
   resolvedAt: integer('resolved_at'),
   createdAt: integer('created_at').notNull(),
   updatedAt: integer('updated_at').notNull(),
-});
+}, (table) => [
+  index('idx_memory_item_conflicts_scope_id').on(table.scopeId),
+]);
 
 export const memorySummaries = sqliteTable('memory_summaries', {
   id: text('id').primaryKey(),
@@ -119,7 +133,9 @@ export const memorySummaries = sqliteTable('memory_summaries', {
   endAt: integer('end_at').notNull(),
   createdAt: integer('created_at').notNull(),
   updatedAt: integer('updated_at').notNull(),
-});
+}, (table) => [
+  index('idx_memory_summaries_scope_id').on(table.scopeId),
+]);
 
 export const memoryEmbeddings = sqliteTable('memory_embeddings', {
   id: text('id').primaryKey(),
@@ -551,6 +567,8 @@ export const callSessions = sqliteTable('call_sessions', {
   status: text('status').notNull().default('initiated'),
   callerIdentityMode: text('caller_identity_mode'),
   callerIdentitySource: text('caller_identity_source'),
+  assistantId: text('assistant_id'),
+  initiatedFromConversationId: text('initiated_from_conversation_id'),
   startedAt: integer('started_at'),
   endedAt: integer('ended_at'),
   lastError: text('last_error'),
@@ -680,3 +698,206 @@ export const channelGuardianRateLimits = sqliteTable('channel_guardian_rate_limi
   createdAt: integer('created_at').notNull(),
   updatedAt: integer('updated_at').notNull(),
 });
+
+// ── Media Assets ─────────────────────────────────────────────────────
+
+export const mediaAssets = sqliteTable('media_assets', {
+  id: text('id').primaryKey(),
+  title: text('title').notNull(),
+  filePath: text('file_path').notNull(),
+  mimeType: text('mime_type').notNull(),
+  durationSeconds: real('duration_seconds'),
+  fileHash: text('file_hash').notNull(),
+  status: text('status').notNull().default('registered'),       // registered | processing | indexed | failed
+  mediaType: text('media_type').notNull(),                      // video | audio | image
+  metadata: text('metadata'),                                   // JSON
+  createdAt: integer('created_at').notNull(),
+  updatedAt: integer('updated_at').notNull(),
+});
+
+export const processingStages = sqliteTable('processing_stages', {
+  id: text('id').primaryKey(),
+  assetId: text('asset_id').notNull()
+    .references(() => mediaAssets.id, { onDelete: 'cascade' }),
+  stage: text('stage').notNull(),
+  status: text('status').notNull().default('pending'),          // pending | running | completed | failed
+  progress: integer('progress').notNull().default(0),           // 0-100
+  lastError: text('last_error'),
+  startedAt: integer('started_at'),
+  completedAt: integer('completed_at'),
+});
+
+export const mediaKeyframes = sqliteTable('media_keyframes', {
+  id: text('id').primaryKey(),
+  assetId: text('asset_id').notNull()
+    .references(() => mediaAssets.id, { onDelete: 'cascade' }),
+  timestamp: real('timestamp').notNull(),
+  filePath: text('file_path').notNull(),
+  metadata: text('metadata'),                                   // JSON
+  createdAt: integer('created_at').notNull(),
+});
+
+export const mediaVisionOutputs = sqliteTable('media_vision_outputs', {
+  id: text('id').primaryKey(),
+  assetId: text('asset_id').notNull()
+    .references(() => mediaAssets.id, { onDelete: 'cascade' }),
+  keyframeId: text('keyframe_id').notNull()
+    .references(() => mediaKeyframes.id, { onDelete: 'cascade' }),
+  analysisType: text('analysis_type').notNull(),
+  output: text('output').notNull(),                             // JSON
+  confidence: real('confidence'),
+  createdAt: integer('created_at').notNull(),
+});
+
+export const mediaTimelines = sqliteTable('media_timelines', {
+  id: text('id').primaryKey(),
+  assetId: text('asset_id').notNull()
+    .references(() => mediaAssets.id, { onDelete: 'cascade' }),
+  startTime: real('start_time').notNull(),
+  endTime: real('end_time').notNull(),
+  segmentType: text('segment_type').notNull(),
+  attributes: text('attributes'),                               // JSON
+  confidence: real('confidence'),
+  createdAt: integer('created_at').notNull(),
+});
+
+export const mediaEvents = sqliteTable('media_events', {
+  id: text('id').primaryKey(),
+  assetId: text('asset_id').notNull()
+    .references(() => mediaAssets.id, { onDelete: 'cascade' }),
+  eventType: text('event_type').notNull(),
+  startTime: real('start_time').notNull(),
+  endTime: real('end_time').notNull(),
+  confidence: real('confidence').notNull(),
+  reasons: text('reasons').notNull(),                            // JSON array
+  metadata: text('metadata'),                                    // JSON
+  createdAt: integer('created_at').notNull(),
+});
+
+export const mediaTrackingProfiles = sqliteTable('media_tracking_profiles', {
+  id: text('id').primaryKey(),
+  assetId: text('asset_id').notNull()
+    .references(() => mediaAssets.id, { onDelete: 'cascade' }),
+  capabilities: text('capabilities').notNull(),                  // JSON: { [capName]: { enabled, tier } }
+  createdAt: integer('created_at').notNull(),
+});
+
+export const mediaEventFeedback = sqliteTable('media_event_feedback', {
+  id: text('id').primaryKey(),
+  assetId: text('asset_id').notNull()
+    .references(() => mediaAssets.id, { onDelete: 'cascade' }),
+  eventId: text('event_id').notNull()
+    .references(() => mediaEvents.id, { onDelete: 'cascade' }),
+  feedbackType: text('feedback_type').notNull(),                 // correct | incorrect | boundary_edit | missed
+  originalStartTime: real('original_start_time'),
+  originalEndTime: real('original_end_time'),
+  correctedStartTime: real('corrected_start_time'),
+  correctedEndTime: real('corrected_end_time'),
+  notes: text('notes'),
+  createdAt: integer('created_at').notNull(),
+});
+
+// ── Guardian Action Requests (cross-channel voice guardian) ──────────
+
+export const guardianActionRequests = sqliteTable('guardian_action_requests', {
+  id: text('id').primaryKey(),
+  assistantId: text('assistant_id').notNull().default('self'),
+  kind: text('kind').notNull(),                                  // 'ask_guardian'
+  sourceChannel: text('source_channel').notNull(),               // 'voice'
+  sourceConversationId: text('source_conversation_id').notNull(),
+  callSessionId: text('call_session_id')
+    .notNull()
+    .references(() => callSessions.id, { onDelete: 'cascade' }),
+  pendingQuestionId: text('pending_question_id')
+    .notNull()
+    .references(() => callPendingQuestions.id, { onDelete: 'cascade' }),
+  questionText: text('question_text').notNull(),
+  requestCode: text('request_code').notNull(),                   // short human-readable code for routing replies
+  status: text('status').notNull().default('pending'),           // pending | answered | expired | cancelled
+  answerText: text('answer_text'),
+  answeredByChannel: text('answered_by_channel'),
+  answeredByExternalUserId: text('answered_by_external_user_id'),
+  answeredAt: integer('answered_at'),
+  expiresAt: integer('expires_at').notNull(),
+  createdAt: integer('created_at').notNull(),
+  updatedAt: integer('updated_at').notNull(),
+});
+
+// ── Guardian Action Deliveries (per-channel delivery tracking) ───────
+
+export const guardianActionDeliveries = sqliteTable('guardian_action_deliveries', {
+  id: text('id').primaryKey(),
+  requestId: text('request_id')
+    .notNull()
+    .references(() => guardianActionRequests.id, { onDelete: 'cascade' }),
+  destinationChannel: text('destination_channel').notNull(),       // 'telegram' | 'sms' | 'macos'
+  destinationConversationId: text('destination_conversation_id'),
+  destinationChatId: text('destination_chat_id'),
+  destinationExternalUserId: text('destination_external_user_id'),
+  status: text('status').notNull().default('pending'),             // pending | sent | failed | answered | expired | cancelled
+  sentAt: integer('sent_at'),
+  respondedAt: integer('responded_at'),
+  lastError: text('last_error'),
+  createdAt: integer('created_at').notNull(),
+  updatedAt: integer('updated_at').notNull(),
+});
+
+// ── Assistant Inbox ──────────────────────────────────────────────────
+
+export const assistantIngressInvites = sqliteTable('assistant_ingress_invites', {
+  id: text('id').primaryKey(),
+  assistantId: text('assistant_id').notNull().default('self'),
+  sourceChannel: text('source_channel').notNull(),
+  tokenHash: text('token_hash').notNull(),
+  createdBySessionId: text('created_by_session_id'),
+  note: text('note'),
+  maxUses: integer('max_uses').notNull().default(1),
+  useCount: integer('use_count').notNull().default(0),
+  expiresAt: integer('expires_at').notNull(),
+  status: text('status').notNull().default('active'),
+  redeemedByExternalUserId: text('redeemed_by_external_user_id'),
+  redeemedByExternalChatId: text('redeemed_by_external_chat_id'),
+  redeemedAt: integer('redeemed_at'),
+  createdAt: integer('created_at').notNull(),
+  updatedAt: integer('updated_at').notNull(),
+});
+
+export const assistantIngressMembers = sqliteTable('assistant_ingress_members', {
+  id: text('id').primaryKey(),
+  assistantId: text('assistant_id').notNull().default('self'),
+  sourceChannel: text('source_channel').notNull(),
+  externalUserId: text('external_user_id'),
+  externalChatId: text('external_chat_id'),
+  displayName: text('display_name'),
+  username: text('username'),
+  status: text('status').notNull().default('pending'),
+  policy: text('policy').notNull().default('allow'),
+  inviteId: text('invite_id')
+    .references(() => assistantIngressInvites.id),
+  createdBySessionId: text('created_by_session_id'),
+  revokedReason: text('revoked_reason'),
+  blockedReason: text('blocked_reason'),
+  lastSeenAt: integer('last_seen_at'),
+  createdAt: integer('created_at').notNull(),
+  updatedAt: integer('updated_at').notNull(),
+});
+
+export const assistantInboxThreadState = sqliteTable('assistant_inbox_thread_state', {
+  conversationId: text('conversation_id')
+    .primaryKey()
+    .references(() => conversations.id, { onDelete: 'cascade' }),
+  assistantId: text('assistant_id').notNull().default('self'),
+  sourceChannel: text('source_channel').notNull(),
+  externalChatId: text('external_chat_id').notNull(),
+  externalUserId: text('external_user_id'),
+  displayName: text('display_name'),
+  username: text('username'),
+  lastInboundAt: integer('last_inbound_at'),
+  lastOutboundAt: integer('last_outbound_at'),
+  lastMessageAt: integer('last_message_at'),
+  unreadCount: integer('unread_count').notNull().default(0),
+  pendingEscalationCount: integer('pending_escalation_count').notNull().default(0),
+  hasPendingEscalation: integer('has_pending_escalation').notNull().default(0),
+  createdAt: integer('created_at').notNull(),
+  updatedAt: integer('updated_at').notNull(),
+});

package/src/memory/search/entity.ts

@@ -1,14 +1,14 @@
 import { and, desc, eq, inArray, isNull, or } from 'drizzle-orm';
 import type { MemoryEntityConfig } from '../../config/types.js';
 import { getLogger } from '../../util/logger.js';
-import { getDb } from '../db.js';
+import { getDb, rawAll } from '../db.js';
 import {
   memoryEntityRelations,
   memoryItemEntities,
   memoryItems,
   memoryItemSources,
 } from '../schema.js';
-import type { Candidate, CandidateSource, CandidateType, EntitySearchResult, MatchedEntityRow } from './types.js';
+import type { Candidate, CandidateSource, CandidateType, EntitySearchResult, MatchedEntityRow, TraversalOptions, TraversalResult, TraversalStep } from './types.js';
 import { computeRecencyScore } from './ranking.js';
 
 const log = getLogger('memory-retriever');
@@ -51,15 +51,16 @@ export function entitySearch(
   }
 
   const relationSeedEntityCount = seedEntityIds.length;
+
   const {
     neighborEntityIds,
     traversedEdgeCount: relationTraversedEdgeCount,
-  } = findNeighborEntities(
-    seedEntityIds,
-    relationConfig.maxEdges,
-    relationConfig.maxNeighborEntities,
-    relationConfig.maxDepth,
-  );
+    neighborDepths,
+  } = findNeighborEntities(seedEntityIds, {
+    maxEdges: relationConfig.maxEdges,
+    maxNeighborEntities: relationConfig.maxNeighborEntities,
+    maxDepth: relationConfig.maxDepth,
+  });
   const relationNeighborEntityCount = neighborEntityIds.length;
   const directItemIds = new Set(directCandidates.map((candidate) => candidate.id));
   const relationCandidates = getEntityLinkedItemCandidates(neighborEntityIds, {
@@ -70,12 +71,47 @@ export function entitySearch(
   });
   const relationExpandedItemCount = relationCandidates.length;
 
+  // Build candidate key → BFS depth map so ranking can apply distance-based decay
+  const candidateDepths = new Map<string, number>();
+  if (relationCandidates.length > 0 && neighborDepths.size > 0) {
+    const db = getDb();
+    const itemIds = relationCandidates.map((c) => c.id);
+    const links = db
+      .select({
+        memoryItemId: memoryItemEntities.memoryItemId,
+        entityId: memoryItemEntities.entityId,
+      })
+      .from(memoryItemEntities)
+      .where(inArray(memoryItemEntities.memoryItemId, itemIds))
+      .all();
+
+    // For each item, find the minimum depth among its linked neighbor entities
+    const itemDepthMap = new Map<string, number>();
+    for (const link of links) {
+      const depth = neighborDepths.get(link.entityId);
+      if (depth !== undefined) {
+        const existing = itemDepthMap.get(link.memoryItemId);
+        if (existing === undefined || depth < existing) {
+          itemDepthMap.set(link.memoryItemId, depth);
+        }
+      }
+    }
+
+    for (const candidate of relationCandidates) {
+      const depth = itemDepthMap.get(candidate.id);
+      if (depth !== undefined) {
+        candidateDepths.set(candidate.key, depth);
+      }
+    }
+  }
+
   return {
     candidates: [...directCandidates, ...relationCandidates],
     relationSeedEntityCount,
     relationTraversedEdgeCount,
     relationNeighborEntityCount,
     relationExpandedItemCount,
+    candidateDepths,
   };
 }
 
@@ -86,6 +122,7 @@ export function emptyEntitySearchResult(): EntitySearchResult {
     relationTraversedEdgeCount: 0,
     relationNeighborEntityCount: 0,
     relationExpandedItemCount: 0,
+    candidateDepths: new Map(),
   };
 }
 
@@ -93,8 +130,6 @@ export function findMatchedEntities(query: string, maxMatches: number): MatchedE
   const trimmed = query.trim();
   if (trimmed.length === 0) return [];
 
-  const db = getDb();
-  const raw = (db as unknown as { $client: { query: (q: string) => { all: (...params: unknown[]) => unknown[] } } }).$client;
   const safeLimit = Math.max(1, Math.floor(maxMatches));
 
   // Tokenize query into words for entity matching (min length 3 to reduce false positives)
@@ -136,14 +171,12 @@ export function findMatchedEntities(query: string, maxMatches: number): MatchedE
     queryParams = [fullQuery, fullQuery];
   }
 
-  let matchedEntities: MatchedEntityRow[] = [];
   try {
-    matchedEntities = raw.query(entityQuery).all(...queryParams) as MatchedEntityRow[];
+    return rawAll<MatchedEntityRow>(entityQuery, ...queryParams);
   } catch (err) {
     log.warn({ err }, 'Entity search query failed');
     return [];
   }
-  return matchedEntities;
 }
 
 /**
@@ -152,18 +185,19 @@ export function findMatchedEntities(query: string, maxMatches: number): MatchedE
  */
 export function findNeighborEntities(
   seedEntityIds: string[],
-  maxEdges: number,
-  maxNeighborEntities: number,
-  maxDepth: number = 3,
-): { neighborEntityIds: string[]; traversedEdgeCount: number } {
+  opts: TraversalOptions,
+): TraversalResult {
+  const { maxEdges, maxNeighborEntities, maxDepth = 3, relationTypes, entityTypes, directed } = opts;
   if (seedEntityIds.length === 0 || maxEdges <= 0 || maxNeighborEntities <= 0 || maxDepth <= 0) {
-    return { neighborEntityIds: [], traversedEdgeCount: 0 };
+    return { neighborEntityIds: [], traversedEdgeCount: 0, neighborDepths: new Map() };
   }
 
   const db = getDb();
   const visited = new Set<string>(seedEntityIds);
   const neighbors: string[] = [];
+  const neighborDepths = new Map<string, number>();
   let totalEdgesTraversed = 0;
+  const filterByEntityType = entityTypes && entityTypes.length > 0;
 
   // BFS frontier starts with seed entities
   let frontier = [...seedEntityIds];
@@ -174,19 +208,86 @@ export function findNeighborEntities(
     const edgeBudget = maxEdges - totalEdgesTraversed;
     if (edgeBudget <= 0) break;
 
-    const rows = db
-      .select({
-        sourceEntityId: memoryEntityRelations.sourceEntityId,
-        targetEntityId: memoryEntityRelations.targetEntityId,
-      })
-      .from(memoryEntityRelations)
-      .where(or(
-        inArray(memoryEntityRelations.sourceEntityId, frontier),
-        inArray(memoryEntityRelations.targetEntityId, frontier),
-      ))
-      .orderBy(desc(memoryEntityRelations.lastSeenAt))
-      .limit(Math.max(1, edgeBudget))
-      .all();
+    let rows: Array<{ sourceEntityId: string; targetEntityId: string }>;
+
+    if (filterByEntityType) {
+      // When filtering by entity type, JOIN with memoryEntities on the neighbor
+      // side so non-matching edges are excluded at the SQL level and don't
+      // consume the edge budget.
+      const relationTypeCondition = relationTypes && relationTypes.length > 0
+        ? `AND r.relation IN (${relationTypes.map(() => '?').join(',')})`
+        : '';
+      const entityTypeFilter = `AND me.type IN (${entityTypes.map(() => '?').join(',')})`;
+      const frontierPlaceholders = frontier.map(() => '?').join(',');
+      const limit = Math.max(1, edgeBudget);
+
+      const relationParams = relationTypes && relationTypes.length > 0 ? relationTypes : [];
+
+      type EdgeRow = { sourceEntityId: string; targetEntityId: string };
+
+      if (directed) {
+        // GROUP BY deduplicates entity pairs that have multiple relation rows
+        const q1 = `
+          SELECT r.source_entity_id AS sourceEntityId, r.target_entity_id AS targetEntityId
+          FROM memory_entity_relations r
+          INNER JOIN memory_entities me ON me.id = r.target_entity_id
+          WHERE r.source_entity_id IN (${frontierPlaceholders})
+          ${relationTypeCondition} ${entityTypeFilter}
+          GROUP BY r.source_entity_id, r.target_entity_id
+          ORDER BY MAX(r.last_seen_at) DESC
+          LIMIT ?
+        `;
+        rows = rawAll<EdgeRow>(q1, ...frontier, ...relationParams, ...entityTypes, limit);
+      } else {
+        // Combine both directions in a single query with global recency
+        // ordering so the edge budget isn't direction-biased.
+        const q = `
+          SELECT sourceEntityId, targetEntityId FROM (
+            SELECT r.source_entity_id AS sourceEntityId, r.target_entity_id AS targetEntityId, r.last_seen_at
+            FROM memory_entity_relations r
+            INNER JOIN memory_entities me ON me.id = r.target_entity_id
+            WHERE r.source_entity_id IN (${frontierPlaceholders})
+            ${relationTypeCondition} ${entityTypeFilter}
+            UNION ALL
+            SELECT r.source_entity_id AS sourceEntityId, r.target_entity_id AS targetEntityId, r.last_seen_at
+            FROM memory_entity_relations r
+            INNER JOIN memory_entities me ON me.id = r.source_entity_id
+            WHERE r.target_entity_id IN (${frontierPlaceholders})
+            ${relationTypeCondition} ${entityTypeFilter}
+          )
+          GROUP BY sourceEntityId, targetEntityId
+          ORDER BY MAX(last_seen_at) DESC
+          LIMIT ?
+        `;
+        rows = rawAll<EdgeRow>(
+          q,
+          ...frontier, ...relationParams, ...entityTypes,
+          ...frontier, ...relationParams, ...entityTypes,
+          limit,
+        );
+      }
+    } else {
+      const frontierCondition = directed
+        ? inArray(memoryEntityRelations.sourceEntityId, frontier)
+        : or(
+            inArray(memoryEntityRelations.sourceEntityId, frontier),
+            inArray(memoryEntityRelations.targetEntityId, frontier),
+          );
+      const whereCondition = relationTypes && relationTypes.length > 0
+        ? and(frontierCondition, inArray(memoryEntityRelations.relation, relationTypes))
+        : frontierCondition;
+
+      rows = db
+        .select({
+          sourceEntityId: memoryEntityRelations.sourceEntityId,
+          targetEntityId: memoryEntityRelations.targetEntityId,
+        })
+        .from(memoryEntityRelations)
+        .where(whereCondition)
+        .orderBy(desc(memoryEntityRelations.lastSeenAt))
+        .limit(Math.max(1, edgeBudget))
+        .all();
+    }
 
     totalEdgesTraversed += rows.length;
 
@@ -194,16 +295,20 @@ export function findNeighborEntities(
     const frontierSet = new Set(frontier);
     for (const row of rows) {
       if (neighbors.length >= maxNeighborEntities) break;
+      // In directed mode, only follow source→target (frontier is always on source side)
       if (frontierSet.has(row.sourceEntityId) && !visited.has(row.targetEntityId)) {
         visited.add(row.targetEntityId);
         neighbors.push(row.targetEntityId);
         nextFrontier.push(row.targetEntityId);
+        neighborDepths.set(row.targetEntityId, depth + 1);
       }
+      if (directed) continue;
       if (neighbors.length >= maxNeighborEntities) break;
       if (frontierSet.has(row.targetEntityId) && !visited.has(row.sourceEntityId)) {
         visited.add(row.sourceEntityId);
         neighbors.push(row.sourceEntityId);
         nextFrontier.push(row.sourceEntityId);
+        neighborDepths.set(row.sourceEntityId, depth + 1);
       }
     }
 
@@ -213,6 +318,7 @@ export function findNeighborEntities(
   return {
     neighborEntityIds: neighbors.slice(0, maxNeighborEntities),
     traversedEdgeCount: totalEdgesTraversed,
+    neighborDepths,
   };
 }
 
@@ -296,3 +402,71 @@ export function getEntityLinkedItemCandidates(
     finalScore: 0,
   }));
 }
+
+/**
+ * Multi-step typed traversal: each step expands the frontier through
+ * edges matching the step's relation/entity type filters.
+ * Returns entity IDs reachable after all steps are applied in sequence.
+ */
+export function collectTypedNeighbors(
+  seedEntityIds: string[],
+  steps: TraversalStep[],
+  opts?: { maxResultsPerStep?: number; maxEdgesPerStep?: number },
+): string[] {
+  if (seedEntityIds.length === 0 || steps.length === 0) return [];
+
+  const maxResults = opts?.maxResultsPerStep ?? 20;
+  const maxEdges = opts?.maxEdgesPerStep ?? 40;
+
+  let currentSeeds = seedEntityIds;
+
+  for (const step of steps) {
+    if (currentSeeds.length === 0) break;
+
+    const result = findNeighborEntities(currentSeeds, {
+      maxEdges,
+      maxNeighborEntities: maxResults,
+      maxDepth: 1,
+      relationTypes: step.relationTypes,
+      entityTypes: step.entityTypes,
+      directed: true,
+    });
+
+    currentSeeds = result.neighborEntityIds;
+  }
+
+  return currentSeeds;
+}
+
+/**
+ * Find entities reachable from ALL given seeds via their respective
+ * typed traversal steps, then return the intersection.
+ */
+export function intersectReachable(
+  queries: Array<{
+    seedEntityIds: string[];
+    steps: TraversalStep[];
+  }>,
+  opts?: { maxResultsPerStep?: number; maxEdgesPerStep?: number },
+): string[] {
+  if (queries.length === 0) return [];
+
+  const resultSets: Set<string>[] = [];
+  for (const query of queries) {
+    const result = collectTypedNeighbors(
+      query.seedEntityIds,
+      query.steps,
+      opts,
+    );
+    resultSets.push(new Set(result));
+  }
+
+  if (resultSets.length === 0) return [];
+
+  // Intersect all sets: keep only entities present in ALL sets
+  const intersection = [...resultSets[0]].filter(id =>
+    resultSets.every(set => set.has(id)),
+  );
+
+  return intersection;
+}