@vellumai/assistant 0.3.27 → 0.4.0

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

@@ -0,0 +1,586 @@
+/**
+ * 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, desc, 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;
+}
+
+// ---------------------------------------------------------------------------
+// Call-controller convenience functions
+// ---------------------------------------------------------------------------
+
+/**
+ * Find the most recent pending canonical guardian request for a given call session.
+ * Used by the call-controller's consultation timeout handler.
+ */
+export function getPendingCanonicalRequestByCallSessionId(callSessionId: string): CanonicalGuardianRequest | null {
+  const db = getDb();
+  const row = db
+    .select()
+    .from(canonicalGuardianRequests)
+    .where(
+      and(
+        eq(canonicalGuardianRequests.callSessionId, callSessionId),
+        eq(canonicalGuardianRequests.status, 'pending'),
+      ),
+    )
+    .orderBy(desc(canonicalGuardianRequests.createdAt))
+    .get();
+  return row ? rowToRequest(row) : null;
+}
+
+/**
+ * Find a canonical guardian request by its linked pending question ID.
+ * Used after async dispatch completes to locate the newly created request.
+ */
+export function getCanonicalRequestByPendingQuestionId(questionId: string): CanonicalGuardianRequest | null {
+  const db = getDb();
+  const row = db
+    .select()
+    .from(canonicalGuardianRequests)
+    .where(eq(canonicalGuardianRequests.pendingQuestionId, questionId))
+    .get();
+  return row ? rowToRequest(row) : null;
+}
+
+/**
+ * Expire a canonical guardian request and all its deliveries.
+ * Atomically transitions the request from 'pending' to 'expired'.
+ */
+export function expireCanonicalGuardianRequest(id: string): void {
+  const db = getDb();
+  const now = new Date().toISOString();
+
+  db.update(canonicalGuardianRequests)
+    .set({ status: 'expired', updatedAt: now })
+    .where(
+      and(
+        eq(canonicalGuardianRequests.id, id),
+        eq(canonicalGuardianRequests.status, 'pending'),
+      ),
+    )
+    .run();
+
+  db.update(canonicalGuardianDeliveries)
+    .set({ status: 'expired', updatedAt: now })
+    .where(eq(canonicalGuardianDeliveries.requestId, id))
+    .run();
+}
+
+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,
@@ -36,6 +37,7 @@ export {
   createBinding,
   getActiveBinding,
   type GuardianBinding,
+  listActiveBindingsByAssistant,
   revokeBinding,
 } from './guardian-bindings.js';
 export {

package/src/memory/conversation-crud.ts

@@ -39,7 +39,7 @@ export const messageMetadataSchema = z.object({
   assistantMessageInterface: interfaceIdSchema.optional(),
   subagentNotification: subagentNotificationSchema.optional(),
   // Provenance fields for trust-aware memory gating (M3)
-  provenanceActorRole: z.enum(['guardian', 'non-guardian', 'unverified_channel']).optional(),
+  provenanceTrustClass: z.enum(['guardian', 'trusted_contact', 'unknown']).optional(),
   provenanceSourceChannel: channelIdSchema.optional(),
   provenanceGuardianExternalUserId: z.string().optional(),
   provenanceRequesterIdentifier: z.string().optional(),
@@ -49,14 +49,14 @@ export type MessageMetadata = z.infer<typeof messageMetadataSchema>;
 
 /**
  * Extract provenance metadata fields from a GuardianRuntimeContext.
- * When no guardian context is provided, defaults to 'unverified_channel'
- * because the absence of guardian context means we cannot verify trust —
+ * When no guardian context is provided, defaults to 'unknown' because the
+ * absence of trust context means we cannot verify trust —
  * callers with actual guardian trust should always supply a real context.
  */
 export function provenanceFromGuardianContext(ctx: GuardianRuntimeContext | null | undefined): Record<string, unknown> {
-  if (!ctx) return { provenanceActorRole: 'unverified_channel' };
+  if (!ctx) return { provenanceTrustClass: 'unknown' };
   return {
-    provenanceActorRole: ctx.actorRole,
+    provenanceTrustClass: ctx.trustClass,
     provenanceSourceChannel: ctx.sourceChannel,
     provenanceGuardianExternalUserId: ctx.guardianExternalUserId,
     provenanceRequesterIdentifier: ctx.requesterIdentifier,
@@ -280,7 +280,7 @@ export async function addMessage(conversationId: string, role: string, content:
       const config = getConfig();
       const scopeId = getConversationMemoryScopeId(conversationId);
       const parsed = metadata ? messageMetadataSchema.safeParse(metadata) : null;
-      const provenanceActorRole = parsed?.success ? parsed.data.provenanceActorRole : undefined;
+      const provenanceTrustClass = parsed?.success ? parsed.data.provenanceTrustClass : undefined;
       indexMessageNow({
         messageId: message.id,
         conversationId: message.conversationId,
@@ -288,7 +288,7 @@ export async function addMessage(conversationId: string, role: string, content:
         content: message.content,
         createdAt: message.createdAt,
         scopeId,
-        provenanceActorRole,
+        provenanceTrustClass,
       }, config.memory);
     } catch (err) {
       log.warn({ err, conversationId, messageId: message.id }, 'Failed to index message for memory');

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,9 +32,11 @@ import {
   migrateGuardianVerificationPurpose,
   migrateGuardianVerificationSessions,
   migrateMessagesFtsBackfill,
+  migrateNormalizePhoneIdentities,
   migrateNotificationDeliveryThreadDecision,
   migrateReminderRoutingIntent,
   migrateSchemaIndexesAndColumns,
+  migrateVoiceInviteColumns,
   recoverCrashedMigrations,
   runComplexMigrations,
   runLateMigrations,
@@ -145,5 +150,20 @@ 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);
+
+  // 26. Voice invite columns on assistant_ingress_invites
+  migrateVoiceInviteColumns(database);
+
   validateMigrationState(database);
 }