@vellumai/assistant 0.4.4 → 0.4.6

package/src/memory/migrations/126-backfill-guardian-principal-id.ts

@@ -0,0 +1,210 @@
+import { type DrizzleDb, getSqliteFrom } from '../db-connection.js';
+import { withCrashRecovery } from './validate-migration-state.js';
+
+/**
+ * Backfill guardianPrincipalId for existing channel_guardian_bindings and
+ * canonical_guardian_requests rows.
+ *
+ * Strategy:
+ *
+ * 1. Derive the assistant's canonical principal from the active 'vellum'
+ *    binding's guardianExternalUserId. This is the stable identity used for
+ *    all guardian decisions from the desktop client.
+ *
+ * 2. Backfill channel_guardian_bindings:
+ *    a. For the vellum binding: set guardianPrincipalId = guardianExternalUserId
+ *       (the vellum external user ID IS the canonical principal).
+ *    b. For non-vellum bindings: set guardianPrincipalId to the vellum
+ *       binding's principal (unifying all channels onto one canonical
+ *       principal). Falls back to guardianExternalUserId if no vellum
+ *       binding exists.
+ *
+ * 3. Backfill canonical_guardian_requests (pending only):
+ *    a. If the request has a guardianExternalUserId that maps to an active
+ *       binding, use that binding's guardianPrincipalId (now backfilled).
+ *    b. For desktop-originated requests (sourceType = 'desktop' or
+ *       sourceChannel = 'vellum') that lack guardianExternalUserId,
+ *       use the assistant principal derived in step 1.
+ *    c. Pending requests that cannot be deterministically bound are expired
+ *       (including access_request rows, which are now principal-bound).
+ *
+ * 4. Idempotent: uses checkpoint key + only updates rows with NULL
+ *    guardianPrincipalId.
+ */
+export function migrateBackfillGuardianPrincipalId(database: DrizzleDb): void {
+  withCrashRecovery(database, 'migration_backfill_guardian_principal_id_v3', () => {
+    const raw = getSqliteFrom(database);
+
+    // Guard: tables must exist
+    const bindingsTableExists = raw.query(
+      `SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = 'channel_guardian_bindings'`,
+    ).get();
+    if (!bindingsTableExists) return;
+
+    const requestsTableExists = raw.query(
+      `SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = 'canonical_guardian_requests'`,
+    ).get();
+
+    // Guard: guardian_principal_id column must exist on bindings table
+    const bindingColExists = raw.query(
+      `SELECT 1 FROM pragma_table_info('channel_guardian_bindings') WHERE name = 'guardian_principal_id'`,
+    ).get();
+    if (!bindingColExists) return;
+
+    try {
+      raw.exec('BEGIN');
+
+      // ── Step 1a: Backfill vellum binding first ─────────────────────
+      // The vellum binding's external user ID IS the canonical principal.
+      raw.exec(/*sql*/ `
+        UPDATE channel_guardian_bindings
+        SET guardian_principal_id = guardian_external_user_id,
+            updated_at = ${Date.now()}
+        WHERE status = 'active'
+          AND channel = 'vellum'
+          AND guardian_external_user_id IS NOT NULL
+          AND guardian_principal_id IS NULL
+      `);
+
+      // ── Step 1b: Derive canonical principal from vellum binding ──
+      const vellumRow = raw.query(
+        `SELECT guardian_principal_id FROM channel_guardian_bindings
+         WHERE assistant_id = 'self' AND channel = 'vellum' AND status = 'active'
+         AND guardian_principal_id IS NOT NULL LIMIT 1`,
+      ).get() as { guardian_principal_id: string } | null;
+
+      if (vellumRow) {
+        // Unify non-vellum bindings onto the canonical principal
+        raw.query(
+          `UPDATE channel_guardian_bindings
+           SET guardian_principal_id = ?,
+               updated_at = ${Date.now()}
+           WHERE status = 'active'
+             AND channel != 'vellum'
+             AND guardian_external_user_id IS NOT NULL
+             AND guardian_principal_id IS NULL`,
+        ).run(vellumRow.guardian_principal_id);
+      } else {
+        // No vellum binding — fallback to channel-specific principal
+        raw.exec(/*sql*/ `
+          UPDATE channel_guardian_bindings
+          SET guardian_principal_id = guardian_external_user_id,
+              updated_at = ${Date.now()}
+          WHERE status = 'active'
+            AND guardian_external_user_id IS NOT NULL
+            AND guardian_principal_id IS NULL
+        `);
+      }
+
+      // ── Step 2: Derive assistant principal from vellum binding ─────
+      // The vellum binding's guardianExternalUserId is the canonical
+      // assistant principal used for desktop-originated requests.
+      const vellumBinding = raw.query(
+        `SELECT guardian_external_user_id, guardian_principal_id FROM channel_guardian_bindings WHERE assistant_id = 'self' AND channel = 'vellum' AND status = 'active' LIMIT 1`,
+      ).get() as { guardian_external_user_id: string; guardian_principal_id: string | null } | null;
+
+      // Use the (now-backfilled) principal from the vellum binding
+      const assistantPrincipal = vellumBinding?.guardian_principal_id ?? vellumBinding?.guardian_external_user_id ?? null;
+
+      // ── Step 3: Backfill canonical_guardian_requests ────────────────
+      if (requestsTableExists) {
+        const requestColExists = raw.query(
+          `SELECT 1 FROM pragma_table_info('canonical_guardian_requests') WHERE name = 'guardian_principal_id'`,
+        ).get();
+
+        if (requestColExists) {
+          const now = new Date().toISOString();
+
+          // 3a. Pending requests with a guardianExternalUserId that maps
+          // to an active binding — use the binding's principal.
+          // Includes all kinds; binding is always useful when available.
+          const pendingWithGuardian = raw.query(
+            `SELECT r.id, r.guardian_external_user_id, r.kind
+             FROM canonical_guardian_requests r
+             WHERE r.status = 'pending'
+               AND r.guardian_principal_id IS NULL
+               AND r.guardian_external_user_id IS NOT NULL`,
+          ).all() as Array<{ id: string; guardian_external_user_id: string; kind: string }>;
+
+          // Build a lookup of guardianExternalUserId -> principalId from
+          // active bindings (all already backfilled in step 1).
+          const activeBindings = raw.query(
+            `SELECT guardian_external_user_id, guardian_principal_id
+             FROM channel_guardian_bindings
+             WHERE assistant_id = 'self' AND status = 'active' AND guardian_principal_id IS NOT NULL`,
+          ).all() as Array<{ guardian_external_user_id: string; guardian_principal_id: string }>;
+
+          const externalToP = new Map<string, string>();
+          for (const b of activeBindings) {
+            externalToP.set(b.guardian_external_user_id, b.guardian_principal_id);
+          }
+
+          const updateStmt = raw.prepare(
+            `UPDATE canonical_guardian_requests SET guardian_principal_id = ?, updated_at = ? WHERE id = ?`,
+          );
+          const expireStmt = raw.prepare(
+            `UPDATE canonical_guardian_requests SET status = 'expired', updated_at = ? WHERE id = ?`,
+          );
+
+          const unboundRequestIds: string[] = [];
+
+          for (const req of pendingWithGuardian) {
+            const principal = externalToP.get(req.guardian_external_user_id);
+            if (principal) {
+              updateStmt.run(principal, now, req.id);
+            } else {
+              // Cannot deterministically map — will expire below.
+              unboundRequestIds.push(req.id);
+            }
+          }
+
+          // 3b. Desktop-originated pending requests missing guardian info
+          // entirely — bind to the assistant principal. Only applies to
+          // requests that also lack a guardian external user ID; requests
+          // that carry an external ID but failed step 3a mapping should be
+          // expired, not reassigned.
+          if (assistantPrincipal) {
+            raw.query(
+              `UPDATE canonical_guardian_requests
+               SET guardian_principal_id = ?, updated_at = ?
+               WHERE status = 'pending'
+                 AND guardian_principal_id IS NULL
+                 AND guardian_external_user_id IS NULL
+                 AND (source_type = 'desktop' OR source_channel = 'vellum')`,
+            ).run(assistantPrincipal, now);
+          }
+
+          // 3c. Expire remaining pending requests that still have no
+          // guardian_principal_id. These requests can never be approved
+          // in the principal-based system, so they must be expired
+          // proactively. This includes access_request rows which are
+          // now decisionable and principal-bound.
+          const stillUnbound = raw.query(
+            `SELECT id FROM canonical_guardian_requests
+             WHERE guardian_principal_id IS NULL
+               AND status = 'pending'`,
+          ).all() as Array<{ id: string }>;
+
+          for (const req of stillUnbound) {
+            expireStmt.run(now, req.id);
+          }
+
+          // Also expire requests identified in 3a that had no binding match.
+          for (const id of unboundRequestIds) {
+            const check = raw.query(
+              `SELECT guardian_principal_id FROM canonical_guardian_requests WHERE id = ? AND status = 'pending'`,
+            ).get(id) as { guardian_principal_id: string | null } | null;
+            if (check && !check.guardian_principal_id) {
+              expireStmt.run(now, id);
+            }
+          }
+        }
+      }
+
+      raw.exec('COMMIT');
+    } catch (e) {
+      try { raw.exec('ROLLBACK'); } catch { /* no active transaction */ }
+      throw e;
+    }
+  });
+}

package/src/memory/migrations/index.ts

@@ -65,6 +65,8 @@ export { createCanonicalGuardianTables } from './121-canonical-guardian-requests
 export { migrateCanonicalGuardianRequesterChatId } from './122-canonical-guardian-requester-chat-id.js';
 export { migrateCanonicalGuardianDeliveriesDestinationIndex } from './123-canonical-guardian-deliveries-destination-index.js';
 export { migrateVoiceInviteDisplayMetadata } from './124-voice-invite-display-metadata.js';
+export { migrateGuardianPrincipalIdColumns } from './125-guardian-principal-id-columns.js';
+export { migrateBackfillGuardianPrincipalId } from './126-backfill-guardian-principal-id.js';
 export {
   MIGRATION_REGISTRY,
   type MigrationRegistryEntry,

package/src/memory/migrations/registry.ts

@@ -95,6 +95,11 @@ export const MIGRATION_REGISTRY: MigrationRegistryEntry[] = [
     version: 14,
     description: 'Normalize phone-like identity fields to E.164 format across guardian bindings, verification challenges, canonical requests, ingress members, and rate limits',
   },
+  {
+    key: 'migration_backfill_guardian_principal_id_v2',
+    version: 15,
+    description: 'Backfill guardianPrincipalId for existing channel_guardian_bindings and canonical_guardian_requests rows, expire unresolvable pending requests',
+  },
 ];
 
 export interface MigrationValidationResult {

package/src/memory/schema.ts

@@ -637,6 +637,7 @@ export const channelGuardianBindings = sqliteTable('channel_guardian_bindings',
   channel: text('channel').notNull(),
   guardianExternalUserId: text('guardian_external_user_id').notNull(),
   guardianDeliveryChatId: text('guardian_delivery_chat_id').notNull(),
+  guardianPrincipalId: text('guardian_principal_id'),
   status: text('status').notNull().default('active'),
   verifiedAt: integer('verified_at').notNull(),
   verifiedVia: text('verified_via').notNull().default('challenge'),
@@ -887,6 +888,7 @@ export const canonicalGuardianRequests = sqliteTable('canonical_guardian_request
   requesterExternalUserId: text('requester_external_user_id'),
   requesterChatId: text('requester_chat_id'),
   guardianExternalUserId: text('guardian_external_user_id'),
+  guardianPrincipalId: text('guardian_principal_id'),
   callSessionId: text('call_session_id'),
   pendingQuestionId: text('pending_question_id'),
   questionText: text('question_text'),
@@ -896,6 +898,7 @@ export const canonicalGuardianRequests = sqliteTable('canonical_guardian_request
   status: text('status').notNull().default('pending'),
   answerText: text('answer_text'),
   decidedByExternalUserId: text('decided_by_external_user_id'),
+  decidedByPrincipalId: text('decided_by_principal_id'),
   followupState: text('followup_state'),
   expiresAt: text('expires_at'),
   createdAt: text('created_at').notNull(),

package/src/notifications/copy-composer.ts

@@ -64,7 +64,7 @@ const TEMPLATES: Record<string, CopyTemplate> = {
     const requester = str(payload.senderIdentifier, 'Someone');
     const requestCode = nonEmpty(typeof payload.requestCode === 'string' ? payload.requestCode : undefined);
     const sourceChannel = typeof payload.sourceChannel === 'string' ? payload.sourceChannel : undefined;
-    const callerName = nonEmpty(typeof payload.senderName === 'string' ? payload.senderName : undefined);
+    const callerName = nonEmpty(typeof payload.actorDisplayName === 'string' ? payload.actorDisplayName : undefined);
     const previousMemberStatus = typeof payload.previousMemberStatus === 'string'
       ? payload.previousMemberStatus
       : undefined;
@@ -72,7 +72,7 @@ const TEMPLATES: Record<string, CopyTemplate> = {
 
     // Voice-originated access requests include caller name context
     if (sourceChannel === 'voice' && callerName) {
-      lines.push(`${callerName} (${str(payload.senderExternalUserId, requester)}) is calling and requesting access to the assistant.`);
+      lines.push(`${callerName} (${str(payload.actorExternalId, requester)}) is calling and requesting access to the assistant.`);
     } else {
       lines.push(`${requester} is requesting access to the assistant.`);
     }

package/src/runtime/access-request-helper.ts

@@ -26,6 +26,7 @@ import { emitNotificationSignal } from '../notifications/emit-signal.js';
 import type { NotificationDeliveryResult } from '../notifications/types.js';
 import { getLogger } from '../util/logger.js';
 import { getGuardianBinding } from './channel-guardian-service.js';
+import { ensureVellumGuardianBinding } from './guardian-vellum-migration.js';
 import { GUARDIAN_APPROVAL_TTL_MS } from './routes/channel-route-shared.js';
 
 const log = getLogger('access-request-helper');
@@ -45,10 +46,10 @@ function applyDeliveryStatus(deliveryId: string, result: NotificationDeliveryRes
 export interface AccessRequestParams {
   canonicalAssistantId: string;
   sourceChannel: ChannelId;
-  externalChatId: string;
-  senderExternalUserId?: string;
-  senderName?: string;
-  senderUsername?: string;
+  conversationExternalId: string;
+  actorExternalId?: string;
+  actorDisplayName?: string;
+  actorUsername?: string;
   previousMemberStatus?: MemberStatus;
 }
 
@@ -80,14 +81,14 @@ export function notifyGuardianOfAccessRequest(
   const {
     canonicalAssistantId,
     sourceChannel,
-    externalChatId,
-    senderExternalUserId,
-    senderName,
-    senderUsername,
+    conversationExternalId,
+    actorExternalId,
+    actorDisplayName,
+    actorUsername,
     previousMemberStatus,
   } = params;
 
-  if (!senderExternalUserId) {
+  if (!actorExternalId) {
     return { notified: false, reason: 'no_sender_id' };
   }
 
@@ -97,33 +98,46 @@ export function notifyGuardianOfAccessRequest(
   // 3. null (no guardian identity — notification pipeline uses trusted channels)
   const sourceBinding = getGuardianBinding(canonicalAssistantId, sourceChannel);
   let guardianExternalUserId: string | null = null;
+  let guardianPrincipalId: string | null = null;
   let guardianBindingChannel: string | null = null;
 
   if (sourceBinding) {
     guardianExternalUserId = sourceBinding.guardianExternalUserId;
+    guardianPrincipalId = sourceBinding.guardianPrincipalId;
     guardianBindingChannel = sourceBinding.channel;
   } else {
     const allBindings = listActiveBindingsByAssistant(canonicalAssistantId);
     if (allBindings.length > 0) {
       guardianExternalUserId = allBindings[0].guardianExternalUserId;
+      guardianPrincipalId = allBindings[0].guardianPrincipalId;
       guardianBindingChannel = allBindings[0].channel;
       log.debug(
         { sourceChannel, fallbackChannel: guardianBindingChannel, canonicalAssistantId },
         'Using cross-channel guardian binding fallback for access request',
       );
-    } else {
-      log.debug(
-        { sourceChannel, canonicalAssistantId },
-        'No guardian binding for access request — proceeding without guardian identity',
-      );
     }
   }
 
+  // Self-heal: access_request is now decisionable and requires a principal.
+  // If no binding was found (or the binding lacks a principal), bootstrap the
+  // vellum binding so the request can be properly attributed.
+  if (!guardianPrincipalId) {
+    log.info(
+      { sourceChannel, canonicalAssistantId },
+      'No guardian principal for access request — self-healing vellum binding',
+    );
+    const healedPrincipalId = ensureVellumGuardianBinding(canonicalAssistantId);
+    const vellumBinding = getGuardianBinding(canonicalAssistantId, 'vellum');
+    guardianExternalUserId = vellumBinding?.guardianExternalUserId ?? guardianExternalUserId;
+    guardianPrincipalId = vellumBinding?.guardianPrincipalId ?? healedPrincipalId;
+    guardianBindingChannel = guardianBindingChannel ?? 'vellum';
+  }
+
   // The conversationId is assistant-scoped so the dedupe query below only
   // matches requests for the same assistant. Without this, a pending request
   // from assistant A could be returned for assistant B, allowing the caller
   // to piggyback on A's guardian approval.
-  const conversationId = `access-req-${canonicalAssistantId}-${sourceChannel}-${senderExternalUserId}`;
+  const conversationId = `access-req-${canonicalAssistantId}-${sourceChannel}-${actorExternalId}`;
 
   // Deduplicate: skip creation if there is already a pending canonical request
   // for the same requester on this channel *and* assistant. Still return
@@ -131,21 +145,21 @@ export function notifyGuardianOfAccessRequest(
   // was already notified.
   const existingCanonical = listCanonicalGuardianRequests({
     status: 'pending',
-    requesterExternalUserId: senderExternalUserId,
+    requesterExternalUserId: actorExternalId,
     sourceChannel,
     kind: 'access_request',
     conversationId,
   });
   if (existingCanonical.length > 0) {
     log.debug(
-      { sourceChannel, senderExternalUserId, existingId: existingCanonical[0].id },
+      { sourceChannel, actorExternalId, existingId: existingCanonical[0].id },
       'Skipping duplicate access request notification',
     );
     return { notified: true, created: false, requestId: existingCanonical[0].id };
   }
 
-  const senderIdentifier = senderName || senderUsername || senderExternalUserId;
-  const requestId = `access-req-${canonicalAssistantId}-${sourceChannel}-${senderExternalUserId}-${Date.now()}`;
+  const senderIdentifier = actorDisplayName || actorUsername || actorExternalId;
+  const requestId = `access-req-${canonicalAssistantId}-${sourceChannel}-${actorExternalId}-${Date.now()}`;
 
   const canonicalRequest = createCanonicalGuardianRequest({
     id: requestId,
@@ -153,9 +167,10 @@ export function notifyGuardianOfAccessRequest(
     sourceType: 'channel',
     sourceChannel,
     conversationId,
-    requesterExternalUserId: senderExternalUserId,
-    requesterChatId: externalChatId,
+    requesterExternalUserId: actorExternalId,
+    requesterChatId: conversationExternalId,
     guardianExternalUserId: guardianExternalUserId ?? undefined,
+    guardianPrincipalId: guardianPrincipalId ?? undefined,
     toolName: 'ingress_access_request',
     questionText: `${senderIdentifier} is requesting access to the assistant`,
     expiresAt: new Date(Date.now() + GUARDIAN_APPROVAL_TTL_MS).toISOString(),
@@ -165,7 +180,7 @@ export function notifyGuardianOfAccessRequest(
   void emitNotificationSignal({
     sourceEventName: 'ingress.access_request',
     sourceChannel,
-    sourceSessionId: `access-req-${sourceChannel}-${senderExternalUserId}`,
+    sourceSessionId: `access-req-${sourceChannel}-${actorExternalId}`,
     assistantId: canonicalAssistantId,
     attentionHints: {
       requiresAction: true,
@@ -177,10 +192,10 @@ export function notifyGuardianOfAccessRequest(
       requestId,
       requestCode: canonicalRequest.requestCode,
       sourceChannel,
-      externalChatId,
-      senderExternalUserId,
-      senderName: senderName ?? null,
-      senderUsername: senderUsername ?? null,
+      conversationExternalId,
+      actorExternalId,
+      actorDisplayName: actorDisplayName ?? null,
+      actorUsername: actorUsername ?? null,
       senderIdentifier,
       guardianBindingChannel,
       previousMemberStatus: previousMemberStatus ?? null,
@@ -237,13 +252,13 @@ export function notifyGuardianOfAccessRequest(
     })
     .catch((err) => {
       log.error(
-        { err, requestId: canonicalRequest.id, sourceChannel, senderExternalUserId },
+        { err, requestId: canonicalRequest.id, sourceChannel, actorExternalId },
         'Failed to persist access request delivery rows from notification pipeline',
       );
     });
 
   log.info(
-    { sourceChannel, senderExternalUserId, senderIdentifier, guardianBindingChannel },
+    { sourceChannel, actorExternalId, senderIdentifier, guardianBindingChannel },
     'Guardian notified of access request',
   );
 

package/src/runtime/actor-trust-resolver.ts

@@ -35,6 +35,8 @@ export interface ActorTrustContext {
     guardianExternalUserId: string;
     guardianDeliveryChatId: string | null;
   } | null;
+  /** Canonical principal ID from the guardian binding. Nullable for backward compatibility — M5 will make this required. */
+  guardianPrincipalId?: string | null;
   /** Ingress member record, if any, for this sender. */
   memberRecord: IngressMember | null;
   /** Trust classification. */
@@ -56,10 +58,10 @@ export interface ActorTrustContext {
 export interface ResolveActorTrustInput {
   assistantId: string;
   sourceChannel: ChannelId;
-  externalChatId: string;
-  senderExternalUserId?: string;
-  senderUsername?: string;
-  senderDisplayName?: string;
+  conversationExternalId: string;
+  actorExternalId?: string;
+  actorUsername?: string;
+  actorDisplayName?: string;
 }
 
 // ---------------------------------------------------------------------------
@@ -78,16 +80,16 @@ export interface ResolveActorTrustInput {
 export function resolveActorTrust(input: ResolveActorTrustInput): ActorTrustContext {
   const assistantId = DAEMON_INTERNAL_ASSISTANT_ID;
 
-  const rawUserId = typeof input.senderExternalUserId === 'string' && input.senderExternalUserId.trim().length > 0
-    ? input.senderExternalUserId.trim()
+  const rawUserId = typeof input.actorExternalId === 'string' && input.actorExternalId.trim().length > 0
+    ? input.actorExternalId.trim()
     : undefined;
 
-  const senderUsername = typeof input.senderUsername === 'string' && input.senderUsername.trim().length > 0
-    ? input.senderUsername.trim()
+  const senderUsername = typeof input.actorUsername === 'string' && input.actorUsername.trim().length > 0
+    ? input.actorUsername.trim()
     : undefined;
 
-  const senderDisplayName = typeof input.senderDisplayName === 'string' && input.senderDisplayName.trim().length > 0
-    ? input.senderDisplayName.trim()
+  const senderDisplayName = typeof input.actorDisplayName === 'string' && input.actorDisplayName.trim().length > 0
+    ? input.actorDisplayName.trim()
     : undefined;
 
   // Canonical identity: normalize phone-like channels to E.164.
@@ -102,6 +104,7 @@ export function resolveActorTrust(input: ResolveActorTrustInput): ActorTrustCont
     return {
       canonicalSenderId: null,
       guardianBindingMatch: null,
+      guardianPrincipalId: undefined,
       memberRecord: null,
       trustClass: 'unknown',
       actorMetadata: {
@@ -137,7 +140,7 @@ export function resolveActorTrust(input: ResolveActorTrustInput): ActorTrustCont
     assistantId,
     sourceChannel: input.sourceChannel,
     externalUserId: canonicalSenderId,
-    externalChatId: input.externalChatId,
+    externalChatId: input.conversationExternalId,
   });
 
   // In group chats, findMember may match on externalChatId and return a
@@ -181,6 +184,7 @@ export function resolveActorTrust(input: ResolveActorTrustInput): ActorTrustCont
   return {
     canonicalSenderId,
     guardianBindingMatch,
+    guardianPrincipalId: binding?.guardianPrincipalId ?? undefined,
     memberRecord,
     trustClass,
     actorMetadata: {
@@ -202,20 +206,21 @@ export function resolveActorTrust(input: ResolveActorTrustInput): ActorTrustCont
  */
 export function toGuardianRuntimeContextFromTrust(
   ctx: ActorTrustContext,
-  externalChatId: string,
+  conversationExternalId: string,
 ): GuardianRuntimeContext {
   return {
     sourceChannel: ctx.actorMetadata.channel,
     trustClass: ctx.trustClass,
     guardianChatId: ctx.guardianBindingMatch?.guardianDeliveryChatId ??
-      (ctx.trustClass === 'guardian' ? externalChatId : undefined),
+      (ctx.trustClass === 'guardian' ? conversationExternalId : undefined),
     guardianExternalUserId: ctx.guardianBindingMatch?.guardianExternalUserId,
+    guardianPrincipalId: ctx.guardianPrincipalId,
     requesterIdentifier: ctx.actorMetadata.identifier,
     requesterDisplayName: ctx.actorMetadata.displayName,
     requesterSenderDisplayName: ctx.actorMetadata.senderDisplayName,
     requesterMemberDisplayName: ctx.actorMetadata.memberDisplayName,
     requesterExternalUserId: ctx.canonicalSenderId ?? undefined,
-    requesterChatId: externalChatId,
+    requesterChatId: conversationExternalId,
     denialReason: ctx.denialReason,
   };
 }

package/src/runtime/channel-guardian-service.ts

@@ -310,12 +310,18 @@ export function validateAndConsumeChallenge(
     metadata.displayName = actorDisplayName.trim();
   }
 
+  // Unify all channel bindings onto the canonical (vellum) principal so that
+  // cross-channel authorization reduces to strict principal equality.
+  const vellumBinding = getActiveBinding(assistantId, 'vellum');
+  const canonicalPrincipal = vellumBinding?.guardianPrincipalId ?? actorExternalUserId;
+
   // Create the new guardian binding
   const binding = createBinding({
     assistantId,
     channel,
     guardianExternalUserId: actorExternalUserId,
     guardianDeliveryChatId: actorChatId,
+    guardianPrincipalId: canonicalPrincipal,
     verifiedVia: 'challenge',
     metadataJson: Object.keys(metadata).length > 0 ? JSON.stringify(metadata) : null,
   });

package/src/runtime/guardian-context-resolver.ts

@@ -24,6 +24,8 @@ export interface GuardianContext {
   trustClass: ActorTrustClass;
   guardianChatId?: string;
   guardianExternalUserId?: string;
+  /** Canonical principal ID from the guardian binding. Nullable for backward compatibility — M5 will make this required. */
+  guardianPrincipalId?: string | null;
   requesterIdentifier?: string;
   requesterDisplayName?: string;
   requesterSenderDisplayName?: string;
@@ -48,14 +50,15 @@ export function resolveGuardianContext(input: ResolveGuardianContextInput): Guar
   return {
     trustClass: trust.trustClass,
     guardianChatId: trust.guardianBindingMatch?.guardianDeliveryChatId ??
-      (trust.trustClass === 'guardian' ? input.externalChatId : undefined),
+      (trust.trustClass === 'guardian' ? input.conversationExternalId : undefined),
     guardianExternalUserId: canonicalGuardianExternalUserId,
+    guardianPrincipalId: trust.guardianPrincipalId,
     requesterIdentifier: trust.actorMetadata.identifier,
     requesterDisplayName: trust.actorMetadata.displayName,
     requesterSenderDisplayName: trust.actorMetadata.senderDisplayName,
     requesterMemberDisplayName: trust.actorMetadata.memberDisplayName,
     requesterExternalUserId: trust.canonicalSenderId ?? undefined,
-    requesterChatId: input.externalChatId,
+    requesterChatId: input.conversationExternalId,
     memberStatus: trust.memberRecord?.status ?? undefined,
     memberPolicy: trust.memberRecord?.policy ?? undefined,
     denialReason: trust.denialReason,
@@ -150,6 +153,7 @@ export function toGuardianRuntimeContext(sourceChannel: ChannelId, ctx: Guardian
     trustClass: ctx.trustClass,
     guardianChatId: ctx.guardianChatId,
     guardianExternalUserId: ctx.guardianExternalUserId,
+    guardianPrincipalId: ctx.guardianPrincipalId,
     requesterIdentifier: ctx.requesterIdentifier,
     requesterDisplayName: ctx.requesterDisplayName,
     requesterSenderDisplayName: ctx.requesterSenderDisplayName,