@vellumai/assistant 0.4.4 → 0.4.6

package/src/daemon/lifecycle.ts

@@ -4,7 +4,7 @@ import { join } from 'node:path';
 
 import { config as dotenvConfig } from 'dotenv';
 
-import { setPointerCopyGenerator } from '../calls/call-pointer-messages.js';
+import { setPointerMessageProcessor } from '../calls/call-pointer-messages.js';
 import { reconcileCallsOnStartup } from '../calls/call-recovery.js';
 import { setRelayBroadcast } from '../calls/relay-server.js';
 import { TwilioConversationRelayProvider } from '../calls/twilio-provider.js';
@@ -53,7 +53,6 @@ import {
 import { listWorkItems, updateWorkItem } from '../work-items/work-item-store.js';
 import { WorkspaceHeartbeatService } from '../workspace/heartbeat-service.js';
 import { createApprovalConversationGenerator,createApprovalCopyGenerator } from './approval-generators.js';
-import { createPointerCopyGenerator } from './call-pointer-generators.js';
 import { hasNoAuthOverride, hasUngatedNoAuthOverride } from './connection-policy.js';
 import { cleanupPidFile, cleanupPidFileIfOwner, writePid } from './daemon-control.js';
 import { createGuardianActionCopyGenerator, createGuardianFollowUpConversationGenerator } from './guardian-action-generators.js';
@@ -372,7 +371,114 @@ export async function runDaemon(): Promise<void> {
     try {
       await runtimeHttp.start();
       setRelayBroadcast((msg) => server.broadcast(msg));
-      setPointerCopyGenerator(createPointerCopyGenerator());
+      setPointerMessageProcessor(async (conversationId, instruction, requiredFacts) => {
+        const session = await server.getSessionForMessages(conversationId);
+
+        // Constrain pointer generation to a tool-disabled path so call-
+        // status events cannot trigger unintended side-effect tools.
+        // Incrementing toolsDisabledDepth causes the resolveTools callback
+        // to return an empty tool list, preventing the LLM from seeing or
+        // invoking any tools during the pointer agent loop.
+        //
+        // A depth counter (rather than a boolean) ensures that overlapping
+        // pointer requests on the same session don't clear each other's
+        // constraint — each caller increments on entry and decrements in
+        // its own finally block.
+        session.toolsDisabledDepth++;
+        try {
+          const messageId = await session.persistUserMessage(
+            instruction,
+            [],
+            undefined,
+            { pointerInstruction: true },
+            '[Call status event]',
+          );
+
+          // Helper: roll back persisted messages on failure, then reload
+          // in-memory history from the (now cleaned) DB. Reloading avoids
+          // stale-index issues when context compaction reassigns the
+          // messages array during runAgentLoop.
+          const rollback = async (extraMessageIds?: string[]) => {
+            try { conversationStore.deleteMessageById(messageId); } catch { /* best effort */ }
+            for (const id of extraMessageIds ?? []) {
+              try { conversationStore.deleteMessageById(id); } catch { /* best effort */ }
+            }
+            try { await session.loadFromDb(); } catch { /* best effort */ }
+          };
+
+          // Snapshot message IDs before the agent loop so we can diff
+          // afterwards to find exactly which messages this run created,
+          // avoiding positional heuristics that break under concurrency.
+          //
+          // Caveat: the diff captures *all* new messages in the
+          // conversation during the loop window, not just those from
+          // this specific agent loop.  If a concurrent pointer event
+          // falls back to a deterministic addMessage() while our loop
+          // is in flight, that message lands in our diff.  The race
+          // requires two pointer events for the same conversation
+          // within the agent loop window *and* this run must fail or
+          // fail fact-check — narrow enough to accept.  A future
+          // improvement could tag messages with a per-run correlation
+          // ID so rollback only targets its own output.
+          const preRunMessageIds = new Set(
+            conversationStore.getMessages(conversationId).map((m) => m.id),
+          );
+
+          let agentLoopError: string | undefined;
+          let generatedText = '';
+          await session.runAgentLoop(instruction, messageId, (msg) => {
+            if ('type' in msg && msg.type === 'assistant_text_delta' && 'text' in msg) {
+              generatedText += (msg as { text: string }).text;
+            }
+            if ('type' in msg && (msg.type === 'error' || msg.type === 'session_error')) {
+              agentLoopError = 'message' in msg
+                ? (msg as { message: string }).message
+                : 'userMessage' in msg
+                  ? (msg as { userMessage: string }).userMessage
+                  : 'Agent loop failed';
+            }
+          });
+
+          // Identify messages created during this run by diffing against
+          // the pre-run snapshot. This captures all messages added to the
+          // conversation during the loop window, which may include messages
+          // from concurrent pointer events (see over-capture caveat above).
+          const postRunMessages = conversationStore.getMessages(conversationId);
+          const createdMessageIds = postRunMessages
+            .filter((m) => !preRunMessageIds.has(m.id) && m.id !== messageId)
+            .map((m) => m.id);
+
+          if (agentLoopError) {
+            await rollback(createdMessageIds);
+            throw new Error(agentLoopError);
+          }
+
+          // Post-generation fact check: verify the assistant's response
+          // includes all required factual details (phone number, duration,
+          // outcome keyword, etc.). If the model omitted or rewrote them,
+          // remove both the instruction and generated messages and throw so
+          // the deterministic fallback fires.
+          //
+          // Validation uses text accumulated from assistant_text_delta
+          // events during the agent loop rather than a DB lookup, avoiding
+          // any positional ambiguity when concurrent pointer events
+          // interleave messages in the conversation.
+          if (requiredFacts && requiredFacts.length > 0) {
+            const missingFacts = requiredFacts.filter((fact) => !generatedText.includes(fact));
+            if (missingFacts.length > 0) {
+              log.warn(
+                { conversationId, missingFacts },
+                'Generated pointer text failed fact validation — falling back to deterministic',
+              );
+              await rollback(createdMessageIds);
+              throw new Error('Generated pointer text failed fact validation');
+            }
+          }
+        } finally {
+          // Restore tool availability so subsequent turns aren't affected.
+          session.toolsDisabledDepth--;
+        }
+      });
       runtimeHttp.setPairingBroadcast((msg) => server.broadcast(msg as ServerMessage));
       initPairingHandlers(runtimeHttp.getPairingStore(), bearerToken);
       initSlashPairingContext(runtimeHttp.getPairingStore());

package/src/daemon/server.ts

@@ -133,33 +133,41 @@ function makePendingInteractionRegistrar(
 
       // Create a canonical guardian request so IPC/HTTP handlers can find it
       // via applyCanonicalGuardianDecision.
-      const guardianContext = session.guardianContext;
-      const sourceChannel = guardianContext?.sourceChannel ?? 'vellum';
-      const canonicalRequest = createCanonicalGuardianRequest({
-        id: msg.requestId,
-        kind: 'tool_approval',
-        sourceType: resolveCanonicalRequestSourceType(sourceChannel),
-        sourceChannel,
-        conversationId,
-        requesterExternalUserId: guardianContext?.requesterExternalUserId,
-        requesterChatId: guardianContext?.requesterChatId,
-        guardianExternalUserId: guardianContext?.guardianExternalUserId,
-        toolName: msg.toolName,
-        status: 'pending',
-        requestCode: generateCanonicalRequestCode(),
-        expiresAt: new Date(Date.now() + 5 * 60 * 1000).toISOString(),
-      });
-
-      // For trusted-contact sessions, bridge to guardian.question so the
-      // guardian gets notified and can approve via callback/request-code.
-      if (guardianContext) {
-        bridgeConfirmationRequestToGuardian({
-          canonicalRequest,
-          guardianContext,
+      try {
+        const guardianContext = session.guardianContext;
+        const sourceChannel = guardianContext?.sourceChannel ?? 'vellum';
+        const canonicalRequest = createCanonicalGuardianRequest({
+          id: msg.requestId,
+          kind: 'tool_approval',
+          sourceType: resolveCanonicalRequestSourceType(sourceChannel),
+          sourceChannel,
           conversationId,
+          requesterExternalUserId: guardianContext?.requesterExternalUserId,
+          requesterChatId: guardianContext?.requesterChatId,
+          guardianExternalUserId: guardianContext?.guardianExternalUserId,
+          guardianPrincipalId: guardianContext?.guardianPrincipalId ?? undefined,
           toolName: msg.toolName,
-          assistantId: session.assistantId ?? DAEMON_INTERNAL_ASSISTANT_ID,
+          status: 'pending',
+          requestCode: generateCanonicalRequestCode(),
+          expiresAt: new Date(Date.now() + 5 * 60 * 1000).toISOString(),
         });
+
+        // For trusted-contact sessions, bridge to guardian.question so the
+        // guardian gets notified and can approve via callback/request-code.
+        if (guardianContext) {
+          bridgeConfirmationRequestToGuardian({
+            canonicalRequest,
+            guardianContext,
+            conversationId,
+            toolName: msg.toolName,
+            assistantId: session.assistantId ?? DAEMON_INTERNAL_ASSISTANT_ID,
+          });
+        }
+      } catch (err) {
+        log.debug(
+          { err, requestId: msg.requestId, conversationId },
+          'Failed to create canonical request from pending interaction registrar',
+        );
       }
     } else if (msg.type === 'secret_request') {
       pendingInteractions.register(msg.requestId, {

package/src/daemon/session-agent-loop.ts

@@ -111,6 +111,7 @@ export interface AgentLoopSessionContext {
 
   readonly coreToolNames: Set<string>;
   allowedToolNames?: Set<string>;
+  toolsDisabledDepth: number;
   preactivatedSkillIds?: string[];
   readonly skillProjectionState: Map<string, string>;
   readonly skillProjectionCache: SkillProjectionCache;
@@ -405,9 +406,9 @@ export async function runAgentLoopImpl(
         const actorTrust = resolveActorTrust({
           assistantId: ctx.assistantId ?? DAEMON_INTERNAL_ASSISTANT_ID,
           sourceChannel: gc.sourceChannel,
-          externalChatId: gc.requesterChatId,
-          senderExternalUserId: gc.requesterExternalUserId,
-          senderDisplayName: gc.requesterSenderDisplayName,
+          conversationExternalId: gc.requesterChatId,
+          actorExternalId: gc.requesterExternalUserId,
+          actorDisplayName: gc.requesterSenderDisplayName,
         });
         resolvedInboundActorContext = inboundActorContextFromTrust(actorTrust);
       } else {

package/src/daemon/session-lifecycle.ts

@@ -29,19 +29,11 @@ type GuardianTrustClass = GuardianRuntimeContext['trustClass'];
 function parseProvenanceTrustClass(metadata: string | null): GuardianTrustClass | undefined {
   if (!metadata) return undefined;
   try {
-    const parsed = JSON.parse(metadata) as {
-      provenanceTrustClass?: unknown;
-      provenanceActorRole?: unknown;
-    };
+    const parsed = JSON.parse(metadata) as { provenanceTrustClass?: unknown };
     const trustClass = parsed?.provenanceTrustClass;
     if (trustClass === 'guardian' || trustClass === 'trusted_contact' || trustClass === 'unknown') {
       return trustClass;
     }
-    // Legacy fallback for rows persisted before provenanceTrustClass existed.
-    const legacyRole = parsed?.provenanceActorRole;
-    if (legacyRole === 'guardian') return 'guardian';
-    if (legacyRole === 'non-guardian') return 'trusted_contact';
-    if (legacyRole === 'unverified_channel') return 'unknown';
   } catch {
     // Ignore malformed metadata and treat as unknown provenance.
   }

package/src/daemon/session-process.ts

@@ -383,9 +383,9 @@ export async function processMessage(
       messageText: trimmedContent,
       channel: 'vellum',
       actor: {
-        externalUserId: undefined,
+        externalUserId: session.guardianContext?.guardianExternalUserId,
         channel: 'vellum',
-        isTrusted: true,
+        guardianPrincipalId: session.guardianContext?.guardianPrincipalId ?? undefined,
       },
       conversationId: session.conversationId,
       pendingRequestIds: canonicalPendingRequestIdsForConversation,

package/src/daemon/session-runtime-assembly.ts

@@ -38,6 +38,8 @@ export interface GuardianRuntimeContext {
   trustClass: 'guardian' | 'trusted_contact' | 'unknown';
   guardianChatId?: string;
   guardianExternalUserId?: string;
+  /** Canonical principal ID for the guardian binding. Nullable for backward compatibility — M5 will make this required. */
+  guardianPrincipalId?: string | null;
   requesterIdentifier?: string;
   requesterDisplayName?: string;
   requesterSenderDisplayName?: string;

package/src/daemon/session-tool-setup.ts

@@ -307,6 +307,8 @@ export interface SkillProjectionContext {
   readonly skillProjectionCache: SkillProjectionCache;
   readonly coreToolNames: Set<string>;
   allowedToolNames?: Set<string>;
+  /** When > 0, the resolveTools callback returns no tools at all. */
+  toolsDisabledDepth: number;
 }
 
 /**
@@ -322,6 +324,14 @@ export function createResolveToolsCallback(
   if (toolDefs.length === 0) return undefined;
 
   return (history: Message[]) => {
+    // When tools are explicitly disabled (e.g. during pointer generation),
+    // return an empty tool list so the LLM never sees tool definitions and
+    // keep the allowlist empty so no tool execution can slip through.
+    if (ctx.toolsDisabledDepth > 0) {
+      ctx.allowedToolNames = new Set<string>();
+      return [];
+    }
+
     const effectivePreactivated = [
       ...DEFAULT_PREACTIVATED_SKILL_IDS,
       ...(ctx.preactivatedSkillIds ?? []),

package/src/daemon/session.ts

@@ -121,6 +121,7 @@ export class Session {
   /** @internal */ workingDir: string;
   /** @internal */ sandboxOverride?: boolean;
   /** @internal */ allowedToolNames?: Set<string>;
+  /** @internal */ toolsDisabledDepth = 0;
   /** @internal */ preactivatedSkillIds?: string[];
   /** @internal */ coreToolNames: Set<string>;
   /** @internal */ readonly skillProjectionState = new Map<string, string>();

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

@@ -10,6 +10,7 @@
 import { and, desc, eq } from 'drizzle-orm';
 import { v4 as uuid } from 'uuid';
 
+import { IntegrityError } from '../util/errors.js';
 import { getDb, rawChanges } from './db.js';
 import {
   canonicalGuardianDeliveries,
@@ -31,6 +32,7 @@ export interface CanonicalGuardianRequest {
   requesterExternalUserId: string | null;
   requesterChatId: string | null;
   guardianExternalUserId: string | null;
+  guardianPrincipalId: string | null;
   callSessionId: string | null;
   pendingQuestionId: string | null;
   questionText: string | null;
@@ -40,6 +42,7 @@ export interface CanonicalGuardianRequest {
   status: CanonicalRequestStatus;
   answerText: string | null;
   decidedByExternalUserId: string | null;
+  decidedByPrincipalId: string | null;
   followupState: string | null;
   expiresAt: string | null;
   createdAt: string;
@@ -117,6 +120,7 @@ function rowToRequest(row: typeof canonicalGuardianRequests.$inferSelect): Canon
     requesterExternalUserId: row.requesterExternalUserId,
     requesterChatId: row.requesterChatId,
     guardianExternalUserId: row.guardianExternalUserId,
+    guardianPrincipalId: row.guardianPrincipalId,
     callSessionId: row.callSessionId,
     pendingQuestionId: row.pendingQuestionId,
     questionText: row.questionText,
@@ -126,6 +130,7 @@ function rowToRequest(row: typeof canonicalGuardianRequests.$inferSelect): Canon
     status: row.status as CanonicalRequestStatus,
     answerText: row.answerText,
     decidedByExternalUserId: row.decidedByExternalUserId,
+    decidedByPrincipalId: row.decidedByPrincipalId,
     followupState: row.followupState,
     expiresAt: row.expiresAt,
     createdAt: row.createdAt,
@@ -160,6 +165,7 @@ export interface CreateCanonicalGuardianRequestParams {
   requesterExternalUserId?: string;
   requesterChatId?: string;
   guardianExternalUserId?: string;
+  guardianPrincipalId?: string;
   callSessionId?: string;
   pendingQuestionId?: string;
   questionText?: string;
@@ -169,11 +175,35 @@ export interface CreateCanonicalGuardianRequestParams {
   status?: CanonicalRequestStatus;
   answerText?: string;
   decidedByExternalUserId?: string;
+  decidedByPrincipalId?: string;
   followupState?: string;
   expiresAt?: string;
 }
 
+/**
+ * Request kinds that require a guardian decision (approve/deny). These kinds
+ * MUST have a `guardianPrincipalId` bound at creation time so the decision
+ * can be attributed to a specific principal. Informational kinds (e.g. status
+ * updates) are exempt from this requirement.
+ */
+const DECISIONABLE_KINDS = new Set([
+  'tool_approval',
+  'tool_grant_request',
+  'pending_question',
+  'access_request',
+]);
+
 export function createCanonicalGuardianRequest(params: CreateCanonicalGuardianRequestParams): CanonicalGuardianRequest {
+  // Guard: decisionable request kinds must have a principal bound at creation
+  // time. This ensures every request that will eventually require a guardian
+  // decision is attributable to a specific identity. Informational kinds are
+  // exempt — they don't participate in the approval flow.
+  if (DECISIONABLE_KINDS.has(params.kind) && !params.guardianPrincipalId) {
+    throw new IntegrityError(
+      `Cannot create decisionable canonical request of kind '${params.kind}' without guardianPrincipalId`,
+    );
+  }
+
   const db = getDb();
   const now = new Date().toISOString();
   const id = params.id ?? uuid();
@@ -187,6 +217,7 @@ export function createCanonicalGuardianRequest(params: CreateCanonicalGuardianRe
     requesterExternalUserId: params.requesterExternalUserId ?? null,
     requesterChatId: params.requesterChatId ?? null,
     guardianExternalUserId: params.guardianExternalUserId ?? null,
+    guardianPrincipalId: params.guardianPrincipalId ?? null,
     callSessionId: params.callSessionId ?? null,
     pendingQuestionId: params.pendingQuestionId ?? null,
     questionText: params.questionText ?? null,
@@ -196,6 +227,7 @@ export function createCanonicalGuardianRequest(params: CreateCanonicalGuardianRe
     status: params.status ?? ('pending' as const),
     answerText: params.answerText ?? null,
     decidedByExternalUserId: params.decidedByExternalUserId ?? null,
+    decidedByPrincipalId: params.decidedByPrincipalId ?? null,
     followupState: params.followupState ?? null,
     expiresAt: params.expiresAt ?? null,
     createdAt: now,
@@ -239,6 +271,7 @@ export function getCanonicalGuardianRequestByCode(code: string): CanonicalGuardi
 export interface ListCanonicalGuardianRequestsFilters {
   status?: CanonicalRequestStatus;
   guardianExternalUserId?: string;
+  guardianPrincipalId?: string;
   requesterExternalUserId?: string;
   conversationId?: string;
   sourceType?: string;
@@ -257,6 +290,9 @@ export function listCanonicalGuardianRequests(filters?: ListCanonicalGuardianReq
   if (filters?.guardianExternalUserId) {
     conditions.push(eq(canonicalGuardianRequests.guardianExternalUserId, filters.guardianExternalUserId));
   }
+  if (filters?.guardianPrincipalId) {
+    conditions.push(eq(canonicalGuardianRequests.guardianPrincipalId, filters.guardianPrincipalId));
+  }
   if (filters?.conversationId) {
     conditions.push(eq(canonicalGuardianRequests.conversationId, filters.conversationId));
   }
@@ -292,6 +328,7 @@ export interface UpdateCanonicalGuardianRequestParams {
   status?: CanonicalRequestStatus;
   answerText?: string;
   decidedByExternalUserId?: string;
+  decidedByPrincipalId?: string;
   followupState?: string | null;
   expiresAt?: string;
 }
@@ -307,6 +344,7 @@ export function updateCanonicalGuardianRequest(
   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.decidedByPrincipalId !== undefined) setValues.decidedByPrincipalId = updates.decidedByPrincipalId;
   if (updates.followupState !== undefined) setValues.followupState = updates.followupState;
   if (updates.expiresAt !== undefined) setValues.expiresAt = updates.expiresAt;
 
@@ -322,6 +360,7 @@ export interface ResolveDecision {
   status: CanonicalRequestStatus;
   answerText?: string;
   decidedByExternalUserId?: string;
+  decidedByPrincipalId?: string;
 }
 
 /**
@@ -343,6 +382,7 @@ export function resolveCanonicalGuardianRequest(
   };
   if (decision.answerText !== undefined) setValues.answerText = decision.answerText;
   if (decision.decidedByExternalUserId !== undefined) setValues.decidedByExternalUserId = decision.decidedByExternalUserId;
+  if (decision.decidedByPrincipalId !== undefined) setValues.decidedByPrincipalId = decision.decidedByPrincipalId;
 
   db.update(canonicalGuardianRequests)
     .set(setValues)

package/src/memory/conversation-crud.ts

@@ -689,3 +689,29 @@ export function getConversationOriginInterface(conversationId: string): Interfac
     .get();
   return parseInterfaceId(row?.originInterface) ?? null;
 }
+
+/**
+ * Return the most recent non-null provenanceTrustClass from user messages
+ * in the given conversation, or `undefined` if none is found.
+ *
+ * Used by the pointer message trust resolver to detect conversations
+ * whose audience is a guardian or trusted_contact (even if the
+ * conversation itself isn't a desktop-origin private thread).
+ */
+export function getConversationRecentProvenanceTrustClass(
+  conversationId: string,
+): 'guardian' | 'trusted_contact' | 'unknown' | undefined {
+  const row = rawGet<{ metadata: string | null }>(
+    `SELECT metadata FROM messages
+     WHERE conversation_id = ? AND role = 'user' AND metadata IS NOT NULL
+     ORDER BY created_at DESC LIMIT 1`,
+    conversationId,
+  );
+  if (!row?.metadata) return undefined;
+  try {
+    const parsed = messageMetadataSchema.safeParse(JSON.parse(row.metadata));
+    return parsed.success ? parsed.data.provenanceTrustClass : undefined;
+  } catch {
+    return undefined;
+  }
+}

package/src/memory/conversation-store.ts

@@ -17,6 +17,7 @@ export {
   getConversationMemoryScopeId,
   getConversationOriginChannel,
   getConversationOriginInterface,
+  getConversationRecentProvenanceTrustClass,
   getConversationThreadType,
   getMessageById,
   getMessages,

package/src/memory/db-init.ts

@@ -19,6 +19,7 @@ import {
   createSequenceTables,
   createTasksAndWorkItemsTables,
   createWatchersAndLogsTables,
+  migrateBackfillGuardianPrincipalId,
   migrateCallSessionMode,
   migrateCanonicalGuardianDeliveriesDestinationIndex,
   migrateCanonicalGuardianRequesterChatId,
@@ -30,6 +31,7 @@ import {
   migrateGuardianActionToolMetadata,
   migrateGuardianBootstrapToken,
   migrateGuardianDeliveryConversationIndex,
+  migrateGuardianPrincipalIdColumns,
   migrateGuardianVerificationPurpose,
   migrateGuardianVerificationSessions,
   migrateMessagesFtsBackfill,
@@ -173,5 +175,11 @@ export function initializeDb(): void {
   // 28. Actor token records (hash-only actor token persistence)
   createActorTokenRecordsTable(database);
 
+  // 29. Guardian principal ID columns on channel_guardian_bindings and canonical_guardian_requests
+  migrateGuardianPrincipalIdColumns(database);
+
+  // 30. Backfill guardianPrincipalId for existing bindings and requests, expire unresolvable pending requests
+  migrateBackfillGuardianPrincipalId(database);
+
   validateMigrationState(database);
 }

package/src/memory/guardian-bindings.ts

@@ -23,6 +23,7 @@ export interface GuardianBinding {
   channel: string;
   guardianExternalUserId: string;
   guardianDeliveryChatId: string;
+  guardianPrincipalId: string | null;
   status: BindingStatus;
   verifiedAt: number;
   verifiedVia: string;
@@ -42,6 +43,7 @@ function rowToBinding(row: typeof channelGuardianBindings.$inferSelect): Guardia
     channel: row.channel,
     guardianExternalUserId: row.guardianExternalUserId,
     guardianDeliveryChatId: row.guardianDeliveryChatId,
+    guardianPrincipalId: row.guardianPrincipalId,
     status: row.status as BindingStatus,
     verifiedAt: row.verifiedAt,
     verifiedVia: row.verifiedVia,
@@ -60,6 +62,7 @@ export function createBinding(params: {
   channel: string;
   guardianExternalUserId: string;
   guardianDeliveryChatId: string;
+  guardianPrincipalId?: string | null;
   verifiedVia?: string;
   metadataJson?: string | null;
 }): GuardianBinding {
@@ -73,6 +76,7 @@ export function createBinding(params: {
     channel: params.channel,
     guardianExternalUserId: params.guardianExternalUserId,
     guardianDeliveryChatId: params.guardianDeliveryChatId,
+    guardianPrincipalId: params.guardianPrincipalId ?? null,
     status: 'active' as const,
     verifiedAt: now,
     verifiedVia: params.verifiedVia ?? 'challenge',

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

@@ -29,16 +29,9 @@ type ProvenanceTrustClass = 'guardian' | 'trusted_contact' | 'unknown';
 function parseProvenanceTrustClass(rawMetadata: string | null): ProvenanceTrustClass | undefined {
   if (!rawMetadata) return undefined;
   try {
-    const parsedJson: unknown = JSON.parse(rawMetadata);
-    const parsed = messageMetadataSchema.safeParse(parsedJson);
+    const parsed = messageMetadataSchema.safeParse(JSON.parse(rawMetadata));
     if (!parsed.success) return undefined;
-    if (parsed.data.provenanceTrustClass) return parsed.data.provenanceTrustClass;
-    // Legacy fallback for rows written before provenanceTrustClass existed.
-    const legacyRole = (parsedJson as { provenanceActorRole?: unknown }).provenanceActorRole;
-    if (legacyRole === 'guardian') return 'guardian';
-    if (legacyRole === 'non-guardian') return 'trusted_contact';
-    if (legacyRole === 'unverified_channel') return 'unknown';
-    return undefined;
+    return parsed.data.provenanceTrustClass;
   } catch {
     return undefined;
   }

package/src/memory/migrations/125-guardian-principal-id-columns.ts

@@ -0,0 +1,19 @@
+import type { DrizzleDb } from '../db-connection.js';
+
+/**
+ * Add guardian_principal_id columns to channel_guardian_bindings and
+ * canonical_guardian_requests, plus decided_by_principal_id to
+ * canonical_guardian_requests.
+ *
+ * These nullable TEXT columns support the canonical identity binding
+ * cutover — linking guardian bindings and approval requests to a
+ * stable principal identity rather than relying solely on
+ * channel-specific external user IDs.
+ *
+ * Uses ALTER TABLE ADD COLUMN with try/catch for idempotency.
+ */
+export function migrateGuardianPrincipalIdColumns(database: DrizzleDb): void {
+  try { database.run(/*sql*/ `ALTER TABLE channel_guardian_bindings ADD COLUMN guardian_principal_id TEXT`); } catch { /* already exists */ }
+  try { database.run(/*sql*/ `ALTER TABLE canonical_guardian_requests ADD COLUMN guardian_principal_id TEXT`); } catch { /* already exists */ }
+  try { database.run(/*sql*/ `ALTER TABLE canonical_guardian_requests ADD COLUMN decided_by_principal_id TEXT`); } catch { /* already exists */ }
+}