@vellumai/assistant 0.3.26 → 0.3.28

package/src/hooks/templates.ts

@@ -1,6 +1,7 @@
 import { chmodSync, cpSync, type Dirent,readdirSync, readFileSync, rmSync } from 'node:fs';
 import { join } from 'node:path';
 
+import { resolveBundledDir } from '../util/bundled-asset.js';
 import { pathExists } from '../util/fs.js';
 import { getLogger } from '../util/logger.js';
 import { getHooksDir } from '../util/platform.js';
@@ -15,7 +16,7 @@ const log = getLogger('hooks-templates');
  * - Newly installed hooks are disabled by default.
  */
 export function installTemplates(): void {
-  const templatesDir = join(import.meta.dirname ?? __dirname, '../../hook-templates');
+  const templatesDir = resolveBundledDir(import.meta.dirname ?? __dirname, '../../hook-templates', 'hook-templates');
   if (!pathExists(templatesDir)) return;
 
   const hooksDir = getHooksDir();

package/src/memory/canonical-guardian-store.ts

@@ -0,0 +1,524 @@
+/**
+ * Store for canonical guardian requests and deliveries.
+ *
+ * Unifies voice guardian action requests/deliveries and channel guardian
+ * approval requests into a single persistence model.  Resolution uses
+ * compare-and-swap (CAS) semantics: the first writer to transition a
+ * request from the expected status wins.
+ */
+
+import { and, eq } from 'drizzle-orm';
+import { v4 as uuid } from 'uuid';
+
+import { getDb, rawChanges } from './db.js';
+import {
+  canonicalGuardianDeliveries,
+  canonicalGuardianRequests,
+} from './schema.js';
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export type CanonicalRequestStatus = 'pending' | 'approved' | 'denied' | 'expired' | 'cancelled';
+
+export interface CanonicalGuardianRequest {
+  id: string;
+  kind: string;
+  sourceType: string;
+  sourceChannel: string | null;
+  conversationId: string | null;
+  requesterExternalUserId: string | null;
+  requesterChatId: string | null;
+  guardianExternalUserId: string | null;
+  callSessionId: string | null;
+  pendingQuestionId: string | null;
+  questionText: string | null;
+  requestCode: string | null;
+  toolName: string | null;
+  inputDigest: string | null;
+  status: CanonicalRequestStatus;
+  answerText: string | null;
+  decidedByExternalUserId: string | null;
+  followupState: string | null;
+  expiresAt: string | null;
+  createdAt: string;
+  updatedAt: string;
+}
+
+export interface CanonicalGuardianDelivery {
+  id: string;
+  requestId: string;
+  destinationChannel: string;
+  destinationConversationId: string | null;
+  destinationChatId: string | null;
+  destinationMessageId: string | null;
+  status: string;
+  createdAt: string;
+  updatedAt: string;
+}
+
+// ---------------------------------------------------------------------------
+// Request code generation
+// ---------------------------------------------------------------------------
+
+/**
+ * Generate a short human-readable request code (6 hex chars, uppercase).
+ *
+ * Checks for collisions against existing PENDING canonical requests and
+ * retries up to 5 times to avoid code reuse among active requests.
+ */
+export function generateCanonicalRequestCode(): string {
+  const MAX_RETRIES = 5;
+  for (let attempt = 0; attempt < MAX_RETRIES; attempt++) {
+    const code = uuid().replace(/-/g, '').slice(0, 6).toUpperCase();
+    // Only check for collisions among pending requests — resolved requests
+    // with the same code are harmless since getCanonicalGuardianRequestByCode
+    // already filters by status='pending'.
+    const existing = getCanonicalGuardianRequestByCodeInternal(code);
+    if (!existing) return code;
+  }
+  // Last resort: return the code even if it collides (extremely unlikely
+  // with 16^6 = ~16.7M possible codes).
+  return uuid().replace(/-/g, '').slice(0, 6).toUpperCase();
+}
+
+/**
+ * Internal code lookup used by the collision checker. Avoids circular
+ * dependency with the public getCanonicalGuardianRequestByCode by
+ * inlining the same query logic.
+ */
+function getCanonicalGuardianRequestByCodeInternal(code: string): boolean {
+  const db = getDb();
+  const row = db
+    .select()
+    .from(canonicalGuardianRequests)
+    .where(
+      and(
+        eq(canonicalGuardianRequests.requestCode, code),
+        eq(canonicalGuardianRequests.status, 'pending'),
+      ),
+    )
+    .get();
+  return !!row;
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function rowToRequest(row: typeof canonicalGuardianRequests.$inferSelect): CanonicalGuardianRequest {
+  return {
+    id: row.id,
+    kind: row.kind,
+    sourceType: row.sourceType,
+    sourceChannel: row.sourceChannel,
+    conversationId: row.conversationId,
+    requesterExternalUserId: row.requesterExternalUserId,
+    requesterChatId: row.requesterChatId,
+    guardianExternalUserId: row.guardianExternalUserId,
+    callSessionId: row.callSessionId,
+    pendingQuestionId: row.pendingQuestionId,
+    questionText: row.questionText,
+    requestCode: row.requestCode,
+    toolName: row.toolName,
+    inputDigest: row.inputDigest,
+    status: row.status as CanonicalRequestStatus,
+    answerText: row.answerText,
+    decidedByExternalUserId: row.decidedByExternalUserId,
+    followupState: row.followupState,
+    expiresAt: row.expiresAt,
+    createdAt: row.createdAt,
+    updatedAt: row.updatedAt,
+  };
+}
+
+function rowToDelivery(row: typeof canonicalGuardianDeliveries.$inferSelect): CanonicalGuardianDelivery {
+  return {
+    id: row.id,
+    requestId: row.requestId,
+    destinationChannel: row.destinationChannel,
+    destinationConversationId: row.destinationConversationId,
+    destinationChatId: row.destinationChatId,
+    destinationMessageId: row.destinationMessageId,
+    status: row.status,
+    createdAt: row.createdAt,
+    updatedAt: row.updatedAt,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Canonical Guardian Requests
+// ---------------------------------------------------------------------------
+
+export interface CreateCanonicalGuardianRequestParams {
+  id?: string;
+  kind: string;
+  sourceType: string;
+  sourceChannel?: string;
+  conversationId?: string;
+  requesterExternalUserId?: string;
+  requesterChatId?: string;
+  guardianExternalUserId?: string;
+  callSessionId?: string;
+  pendingQuestionId?: string;
+  questionText?: string;
+  requestCode?: string;
+  toolName?: string;
+  inputDigest?: string;
+  status?: CanonicalRequestStatus;
+  answerText?: string;
+  decidedByExternalUserId?: string;
+  followupState?: string;
+  expiresAt?: string;
+}
+
+export function createCanonicalGuardianRequest(params: CreateCanonicalGuardianRequestParams): CanonicalGuardianRequest {
+  const db = getDb();
+  const now = new Date().toISOString();
+  const id = params.id ?? uuid();
+
+  const row = {
+    id,
+    kind: params.kind,
+    sourceType: params.sourceType,
+    sourceChannel: params.sourceChannel ?? null,
+    conversationId: params.conversationId ?? null,
+    requesterExternalUserId: params.requesterExternalUserId ?? null,
+    requesterChatId: params.requesterChatId ?? null,
+    guardianExternalUserId: params.guardianExternalUserId ?? null,
+    callSessionId: params.callSessionId ?? null,
+    pendingQuestionId: params.pendingQuestionId ?? null,
+    questionText: params.questionText ?? null,
+    requestCode: params.requestCode ?? generateCanonicalRequestCode(),
+    toolName: params.toolName ?? null,
+    inputDigest: params.inputDigest ?? null,
+    status: params.status ?? ('pending' as const),
+    answerText: params.answerText ?? null,
+    decidedByExternalUserId: params.decidedByExternalUserId ?? null,
+    followupState: params.followupState ?? null,
+    expiresAt: params.expiresAt ?? null,
+    createdAt: now,
+    updatedAt: now,
+  };
+
+  db.insert(canonicalGuardianRequests).values(row).run();
+  return rowToRequest(row);
+}
+
+export function getCanonicalGuardianRequest(id: string): CanonicalGuardianRequest | null {
+  const db = getDb();
+  const row = db
+    .select()
+    .from(canonicalGuardianRequests)
+    .where(eq(canonicalGuardianRequests.id, id))
+    .get();
+  return row ? rowToRequest(row) : null;
+}
+
+/**
+ * Look up a canonical guardian request by its short request code.
+ * Scoped to pending (unresolved) requests so that codes recycled by older,
+ * already-resolved requests do not collide with the active one.
+ */
+export function getCanonicalGuardianRequestByCode(code: string): CanonicalGuardianRequest | null {
+  const db = getDb();
+  const row = db
+    .select()
+    .from(canonicalGuardianRequests)
+    .where(
+      and(
+        eq(canonicalGuardianRequests.requestCode, code),
+        eq(canonicalGuardianRequests.status, 'pending'),
+      ),
+    )
+    .get();
+  return row ? rowToRequest(row) : null;
+}
+
+export interface ListCanonicalGuardianRequestsFilters {
+  status?: CanonicalRequestStatus;
+  guardianExternalUserId?: string;
+  requesterExternalUserId?: string;
+  conversationId?: string;
+  sourceType?: string;
+  sourceChannel?: string;
+  kind?: string;
+  toolName?: string;
+}
+
+export function listCanonicalGuardianRequests(filters?: ListCanonicalGuardianRequestsFilters): CanonicalGuardianRequest[] {
+  const db = getDb();
+
+  const conditions = [];
+  if (filters?.status) {
+    conditions.push(eq(canonicalGuardianRequests.status, filters.status));
+  }
+  if (filters?.guardianExternalUserId) {
+    conditions.push(eq(canonicalGuardianRequests.guardianExternalUserId, filters.guardianExternalUserId));
+  }
+  if (filters?.conversationId) {
+    conditions.push(eq(canonicalGuardianRequests.conversationId, filters.conversationId));
+  }
+  if (filters?.requesterExternalUserId) {
+    conditions.push(eq(canonicalGuardianRequests.requesterExternalUserId, filters.requesterExternalUserId));
+  }
+  if (filters?.sourceType) {
+    conditions.push(eq(canonicalGuardianRequests.sourceType, filters.sourceType));
+  }
+  if (filters?.sourceChannel) {
+    conditions.push(eq(canonicalGuardianRequests.sourceChannel, filters.sourceChannel));
+  }
+  if (filters?.kind) {
+    conditions.push(eq(canonicalGuardianRequests.kind, filters.kind));
+  }
+  if (filters?.toolName) {
+    conditions.push(eq(canonicalGuardianRequests.toolName, filters.toolName));
+  }
+
+  if (conditions.length === 0) {
+    return db.select().from(canonicalGuardianRequests).all().map(rowToRequest);
+  }
+
+  return db
+    .select()
+    .from(canonicalGuardianRequests)
+    .where(and(...conditions))
+    .all()
+    .map(rowToRequest);
+}
+
+export interface UpdateCanonicalGuardianRequestParams {
+  status?: CanonicalRequestStatus;
+  answerText?: string;
+  decidedByExternalUserId?: string;
+  followupState?: string;
+  expiresAt?: string;
+}
+
+export function updateCanonicalGuardianRequest(
+  id: string,
+  updates: UpdateCanonicalGuardianRequestParams,
+): CanonicalGuardianRequest | null {
+  const db = getDb();
+  const now = new Date().toISOString();
+
+  const setValues: Record<string, unknown> = { updatedAt: now };
+  if (updates.status !== undefined) setValues.status = updates.status;
+  if (updates.answerText !== undefined) setValues.answerText = updates.answerText;
+  if (updates.decidedByExternalUserId !== undefined) setValues.decidedByExternalUserId = updates.decidedByExternalUserId;
+  if (updates.followupState !== undefined) setValues.followupState = updates.followupState;
+  if (updates.expiresAt !== undefined) setValues.expiresAt = updates.expiresAt;
+
+  db.update(canonicalGuardianRequests)
+    .set(setValues)
+    .where(eq(canonicalGuardianRequests.id, id))
+    .run();
+
+  return getCanonicalGuardianRequest(id);
+}
+
+export interface ResolveDecision {
+  status: CanonicalRequestStatus;
+  answerText?: string;
+  decidedByExternalUserId?: string;
+}
+
+/**
+ * Compare-and-swap resolve: only transitions the request from `expectedStatus`
+ * to the new status atomically. Returns the updated request on success, or
+ * null if the current status did not match `expectedStatus` (first-writer-wins).
+ */
+export function resolveCanonicalGuardianRequest(
+  id: string,
+  expectedStatus: CanonicalRequestStatus,
+  decision: ResolveDecision,
+): CanonicalGuardianRequest | null {
+  const db = getDb();
+  const now = new Date().toISOString();
+
+  const setValues: Record<string, unknown> = {
+    status: decision.status,
+    updatedAt: now,
+  };
+  if (decision.answerText !== undefined) setValues.answerText = decision.answerText;
+  if (decision.decidedByExternalUserId !== undefined) setValues.decidedByExternalUserId = decision.decidedByExternalUserId;
+
+  db.update(canonicalGuardianRequests)
+    .set(setValues)
+    .where(
+      and(
+        eq(canonicalGuardianRequests.id, id),
+        eq(canonicalGuardianRequests.status, expectedStatus),
+      ),
+    )
+    .run();
+
+  if (rawChanges() === 0) return null;
+
+  return getCanonicalGuardianRequest(id);
+}
+
+// ---------------------------------------------------------------------------
+// Canonical Guardian Deliveries
+// ---------------------------------------------------------------------------
+
+export interface CreateCanonicalGuardianDeliveryParams {
+  id?: string;
+  requestId: string;
+  destinationChannel: string;
+  destinationConversationId?: string;
+  destinationChatId?: string;
+  destinationMessageId?: string;
+  status?: string;
+}
+
+export function createCanonicalGuardianDelivery(params: CreateCanonicalGuardianDeliveryParams): CanonicalGuardianDelivery {
+  const db = getDb();
+  const now = new Date().toISOString();
+  const id = params.id ?? uuid();
+
+  const row = {
+    id,
+    requestId: params.requestId,
+    destinationChannel: params.destinationChannel,
+    destinationConversationId: params.destinationConversationId ?? null,
+    destinationChatId: params.destinationChatId ?? null,
+    destinationMessageId: params.destinationMessageId ?? null,
+    status: params.status ?? ('pending' as const),
+    createdAt: now,
+    updatedAt: now,
+  };
+
+  db.insert(canonicalGuardianDeliveries).values(row).run();
+  return rowToDelivery(row);
+}
+
+export function listCanonicalGuardianDeliveries(requestId: string): CanonicalGuardianDelivery[] {
+  const db = getDb();
+  return db
+    .select()
+    .from(canonicalGuardianDeliveries)
+    .where(eq(canonicalGuardianDeliveries.requestId, requestId))
+    .all()
+    .map(rowToDelivery);
+}
+
+/**
+ * List pending canonical requests that were delivered to a specific
+ * destination conversation.
+ *
+ * This bridges inbound guardian replies (which arrive on the destination
+ * conversation) back to their canonical request records. The caller can
+ * optionally scope by destination channel when the same conversation ID
+ * namespace could exist across channels.
+ */
+export function listPendingCanonicalGuardianRequestsByDestinationConversation(
+  destinationConversationId: string,
+  destinationChannel?: string,
+): CanonicalGuardianRequest[] {
+  const db = getDb();
+
+  const deliveryConditions = [eq(canonicalGuardianDeliveries.destinationConversationId, destinationConversationId)];
+  if (destinationChannel) {
+    deliveryConditions.push(eq(canonicalGuardianDeliveries.destinationChannel, destinationChannel));
+  }
+
+  const deliveries = db
+    .select()
+    .from(canonicalGuardianDeliveries)
+    .where(and(...deliveryConditions))
+    .all();
+
+  if (deliveries.length === 0) return [];
+
+  const seenRequestIds = new Set<string>();
+  const pendingRequests: CanonicalGuardianRequest[] = [];
+
+  for (const delivery of deliveries) {
+    if (seenRequestIds.has(delivery.requestId)) continue;
+    seenRequestIds.add(delivery.requestId);
+
+    const request = getCanonicalGuardianRequest(delivery.requestId);
+    if (request && request.status === 'pending') {
+      pendingRequests.push(request);
+    }
+  }
+
+  return pendingRequests;
+}
+
+/**
+ * List pending canonical requests that were delivered to a specific
+ * destination chat (channel + chatId pair).
+ *
+ * This bridges inbound guardian replies (which arrive on a specific chat)
+ * back to their canonical request records. Unlike the conversation-based
+ * variant, this uses the chat-level addressing that channel transports
+ * (Telegram, SMS) natively provide — critical for voice-originated
+ * `pending_question` requests that lack `guardianExternalUserId`.
+ */
+export function listPendingCanonicalGuardianRequestsByDestinationChat(
+  destinationChannel: string,
+  destinationChatId: string,
+): CanonicalGuardianRequest[] {
+  const db = getDb();
+
+  const deliveries = db
+    .select()
+    .from(canonicalGuardianDeliveries)
+    .where(
+      and(
+        eq(canonicalGuardianDeliveries.destinationChannel, destinationChannel),
+        eq(canonicalGuardianDeliveries.destinationChatId, destinationChatId),
+      ),
+    )
+    .all();
+
+  if (deliveries.length === 0) return [];
+
+  const seenRequestIds = new Set<string>();
+  const pendingRequests: CanonicalGuardianRequest[] = [];
+
+  for (const delivery of deliveries) {
+    if (seenRequestIds.has(delivery.requestId)) continue;
+    seenRequestIds.add(delivery.requestId);
+
+    const request = getCanonicalGuardianRequest(delivery.requestId);
+    if (request && request.status === 'pending') {
+      pendingRequests.push(request);
+    }
+  }
+
+  return pendingRequests;
+}
+
+export interface UpdateCanonicalGuardianDeliveryParams {
+  status?: string;
+  destinationMessageId?: string;
+}
+
+export function updateCanonicalGuardianDelivery(
+  id: string,
+  updates: UpdateCanonicalGuardianDeliveryParams,
+): CanonicalGuardianDelivery | null {
+  const db = getDb();
+  const now = new Date().toISOString();
+
+  const setValues: Record<string, unknown> = { updatedAt: now };
+  if (updates.status !== undefined) setValues.status = updates.status;
+  if (updates.destinationMessageId !== undefined) setValues.destinationMessageId = updates.destinationMessageId;
+
+  db.update(canonicalGuardianDeliveries)
+    .set(setValues)
+    .where(eq(canonicalGuardianDeliveries.id, id))
+    .run();
+
+  const row = db
+    .select()
+    .from(canonicalGuardianDeliveries)
+    .where(eq(canonicalGuardianDeliveries.id, id))
+    .get();
+
+  return row ? rowToDelivery(row) : null;
+}

package/src/memory/channel-guardian-store.ts

@@ -13,6 +13,7 @@
 export {
   type ApprovalRequestStatus,
   countPendingByConversation,
+  // @internal — test-only helpers; production code uses canonical-guardian-store
   createApprovalRequest,
   findPendingAccessRequestForRequester,
   getAllPendingApprovalsByGuardianChat,

package/src/memory/db-init.ts

@@ -3,6 +3,7 @@ import {
   addCoreColumns,
   createAssistantInboxTables,
   createCallSessionsTables,
+  createCanonicalGuardianTables,
   createChannelGuardianTables,
   createContactsAndTriageTables,
   createConversationAttentionTables,
@@ -18,6 +19,8 @@ import {
   createTasksAndWorkItemsTables,
   createWatchersAndLogsTables,
   migrateCallSessionMode,
+  migrateCanonicalGuardianDeliveriesDestinationIndex,
+  migrateCanonicalGuardianRequesterChatId,
   migrateChannelInboundDeliveredSegments,
   migrateConversationsThreadTypeIndex,
   migrateFkCascadeRebuilds,
@@ -29,6 +32,7 @@ import {
   migrateGuardianVerificationPurpose,
   migrateGuardianVerificationSessions,
   migrateMessagesFtsBackfill,
+  migrateNormalizePhoneIdentities,
   migrateNotificationDeliveryThreadDecision,
   migrateReminderRoutingIntent,
   migrateSchemaIndexesAndColumns,
@@ -145,5 +149,17 @@ export function initializeDb(): void {
   // 23. Thread decision audit columns on notification_deliveries
   migrateNotificationDeliveryThreadDecision(database);
 
+  // 24. Canonical guardian requests and deliveries (unified cross-source guardian domain)
+  createCanonicalGuardianTables(database);
+
+  // 24b. Add requester_chat_id to canonical_guardian_requests (chat ID != user ID on some channels)
+  migrateCanonicalGuardianRequesterChatId(database);
+
+  // 24c. Composite index on canonical_guardian_deliveries(destination_channel, destination_chat_id) for chat-based lookups
+  migrateCanonicalGuardianDeliveriesDestinationIndex(database);
+
+  // 25. Normalize phone-like identity fields to E.164 across guardian and ingress tables
+  migrateNormalizePhoneIdentities(database);
+
   validateMigrationState(database);
 }

package/src/memory/guardian-action-store.ts

@@ -7,7 +7,7 @@
  * answer resolves the request and all other deliveries are marked answered.
  */
 
-import { and, count, desc, eq, inArray, isNotNull, lt } from 'drizzle-orm';
+import { and, desc, eq, inArray, lt } from 'drizzle-orm';
 import { v4 as uuid } from 'uuid';
 
 import { getLogger } from '../util/logger.js';
@@ -136,6 +136,12 @@ function generateRequestCode(): string {
 // Guardian Action Requests
 // ---------------------------------------------------------------------------
 
+/**
+ * @internal Test-only helper. Production code should create guardian requests
+ * via `createCanonicalGuardianRequest` in canonical-guardian-store.ts.
+ * This function is retained solely so that existing test fixtures that seed
+ * legacy guardian action rows continue to compile.
+ */
 export function createGuardianActionRequest(params: {
   assistantId?: string;
   kind: string;
@@ -226,65 +232,6 @@ export function getPendingRequestByCallSessionId(callSessionId: string): Guardia
   return row ? rowToRequest(row) : null;
 }
 
-/**
- * Count pending guardian action requests for a given call session.
- * Used as a candidate-affinity hint so the decision engine knows how many
- * active guardian requests already exist for the current call.
- */
-export function countPendingRequestsByCallSessionId(callSessionId: string): number {
-  const db = getDb();
-  const row = db
-    .select({ count: count() })
-    .from(guardianActionRequests)
-    .where(
-      and(
-        eq(guardianActionRequests.callSessionId, callSessionId),
-        eq(guardianActionRequests.status, 'pending'),
-      ),
-    )
-    .get();
-  return row?.count ?? 0;
-}
-
-/**
- * Look up the vellum conversation ID used for the first guardian question
- * delivery in a given call session. Returns the conversation ID when one
- * exists, or null if no vellum delivery has been recorded yet.
- *
- * Used by guardian-dispatch to enforce deterministic thread affinity:
- * all guardian questions within the same call session should route to
- * the same vellum conversation.
- */
-export function getGuardianConversationIdForCallSession(callSessionId: string): string | null {
-  try {
-    const db = getDb();
-    const row = db
-      .select({ conversationId: guardianActionDeliveries.destinationConversationId })
-      .from(guardianActionDeliveries)
-      .innerJoin(
-        guardianActionRequests,
-        eq(guardianActionDeliveries.requestId, guardianActionRequests.id),
-      )
-      .where(
-        and(
-          eq(guardianActionRequests.callSessionId, callSessionId),
-          eq(guardianActionDeliveries.destinationChannel, 'vellum'),
-          isNotNull(guardianActionDeliveries.destinationConversationId),
-        ),
-      )
-      .orderBy(guardianActionDeliveries.createdAt)
-      .limit(1)
-      .get();
-    return row?.conversationId ?? null;
-  } catch (err) {
-    if (err instanceof Error && err.message.includes('no such table')) {
-      log.warn({ err }, 'guardian tables not yet created');
-      return null;
-    }
-    throw err;
-  }
-}
-
 /**
  * First-response-wins resolution. Checks that the request is still
  * 'pending' before updating; returns the updated request on success

package/src/memory/guardian-approvals.ts

@@ -70,6 +70,12 @@ function rowToApprovalRequest(row: typeof channelGuardianApprovalRequests.$infer
 // Operations
 // ---------------------------------------------------------------------------
 
+/**
+ * @internal Test-only helper. Production code should create guardian requests
+ * via `createCanonicalGuardianRequest` in canonical-guardian-store.ts.
+ * This function is retained solely so that existing test fixtures that seed
+ * legacy approval rows continue to compile.
+ */
 export function createApprovalRequest(params: {
   runId: string;
   requestId?: string;
@@ -535,10 +541,9 @@ export function countPendingByConversation(
 }
 
 /**
- * Check for an existing pending (non-expired) approval request for a specific
- * requester on a channel. Used to deduplicate access requests — repeated
- * messages from the same non-member should not create duplicate approval
- * requests while one is already pending.
+ * @internal Test-only helper. Production code should query canonical guardian
+ * requests via `listCanonicalGuardianRequests` in canonical-guardian-store.ts.
+ * Retained for existing test fixtures that check legacy approval dedup.
  */
 export function findPendingAccessRequestForRequester(
   assistantId: string,