@vellumai/assistant 0.4.4 → 0.4.6

package/src/__tests__/guardian-decision-primitive-canonical.test.ts

@@ -64,11 +64,14 @@ afterAll(() => {
 // Helpers
 // ---------------------------------------------------------------------------
 
+/** Consistent test principal used across all test actors and requests. */
+const TEST_PRINCIPAL_ID = 'test-principal-id';
+
 function guardianActor(overrides: Partial<ActorContext> = {}): ActorContext {
   return {
     externalUserId: 'guardian-1',
     channel: 'telegram',
-    isTrusted: false,
+    guardianPrincipalId: TEST_PRINCIPAL_ID,
     ...overrides,
   };
 }
@@ -77,7 +80,7 @@ function trustedActor(overrides: Partial<ActorContext> = {}): ActorContext {
   return {
     externalUserId: undefined,
     channel: 'desktop',
-    isTrusted: true,
+    guardianPrincipalId: TEST_PRINCIPAL_ID,
     ...overrides,
   };
 }
@@ -120,6 +123,7 @@ describe('applyCanonicalGuardianDecision', () => {
       sourceChannel: 'telegram',
       conversationId: 'conv-1',
       guardianExternalUserId: 'guardian-1',
+      guardianPrincipalId: TEST_PRINCIPAL_ID,
       toolName: 'shell',
       inputDigest: 'sha256:abc',
       expiresAt: new Date(Date.now() + 60_000).toISOString(),
@@ -153,6 +157,7 @@ describe('applyCanonicalGuardianDecision', () => {
       sourceChannel: 'telegram',
       conversationId: 'conv-1',
       guardianExternalUserId: 'guardian-1',
+      guardianPrincipalId: TEST_PRINCIPAL_ID,
       toolName: 'shell',
       inputDigest: 'sha256:abc',
       expiresAt: new Date(Date.now() + 60_000).toISOString(),
@@ -178,6 +183,7 @@ describe('applyCanonicalGuardianDecision', () => {
       sourceType: 'voice',
       sourceChannel: 'twilio',
       guardianExternalUserId: 'guardian-1',
+      guardianPrincipalId: TEST_PRINCIPAL_ID,
       callSessionId: 'call-1',
       pendingQuestionId: 'pq-1',
       questionText: 'What is the gate code?',
@@ -199,21 +205,22 @@ describe('applyCanonicalGuardianDecision', () => {
     expect(resolved!.answerText).toBe('1234');
   });
 
-  // ── Identity mismatch ──────────────────────────────────────────────
+  // ── Principal mismatch ──────────────────────────────────────────────
 
-  test('rejects decision when actor does not match guardian', async () => {
+  test('rejects decision when actor principal does not match request principal', async () => {
     const req = createCanonicalGuardianRequest({
       kind: 'tool_approval',
       sourceType: 'channel',
       conversationId: 'conv-1',
       guardianExternalUserId: 'guardian-1',
+      guardianPrincipalId: TEST_PRINCIPAL_ID,
       expiresAt: new Date(Date.now() + 60_000).toISOString(),
     });
 
     const result = await applyCanonicalGuardianDecision({
       requestId: req.id,
       action: 'approve_once',
-      actorContext: guardianActor({ externalUserId: 'imposter-99' }),
+      actorContext: guardianActor({ guardianPrincipalId: 'wrong-principal' }),
     });
 
     expect(result.applied).toBe(false);
@@ -225,12 +232,13 @@ describe('applyCanonicalGuardianDecision', () => {
     expect(unchanged!.status).toBe('pending');
   });
 
-  test('trusted actor bypasses identity check', async () => {
+  test('matching principal authorizes decision (cross-channel same principal)', async () => {
     const req = createCanonicalGuardianRequest({
       kind: 'tool_approval',
       sourceType: 'desktop',
       conversationId: 'conv-1',
       guardianExternalUserId: 'guardian-1',
+      guardianPrincipalId: TEST_PRINCIPAL_ID,
       toolName: 'shell',
       inputDigest: 'sha256:abc',
       expiresAt: new Date(Date.now() + 60_000).toISOString(),
@@ -243,24 +251,48 @@ describe('applyCanonicalGuardianDecision', () => {
     });
 
     expect(result.applied).toBe(true);
-    // No grant minted because trusted actor has no externalUserId
     if (!result.applied) return;
+    // No grant minted because trusted actor has no externalUserId
     expect(result.grantMinted).toBe(false);
   });
 
-  test('rejects non-trusted decision when tool approval has no guardian binding', async () => {
+  test('rejects decision when request has no guardianPrincipalId', async () => {
+    // unknown_kind is not in DECISIONABLE_KINDS so it can be created without
+    // guardianPrincipalId, but the decision primitive still rejects because
+    // the request is missing its principal binding.
+    const req = createCanonicalGuardianRequest({
+      kind: 'unknown_kind',
+      sourceType: 'channel',
+      conversationId: 'conv-1',
+      guardianExternalUserId: 'guardian-1',
+      expiresAt: new Date(Date.now() + 60_000).toISOString(),
+    });
+
+    const result = await applyCanonicalGuardianDecision({
+      requestId: req.id,
+      action: 'approve_once',
+      actorContext: guardianActor({ guardianPrincipalId: 'some-principal' }),
+    });
+
+    expect(result.applied).toBe(false);
+    if (result.applied) return;
+    expect(result.reason).toBe('identity_mismatch');
+  });
+
+  test('rejects decision when actor has no guardianPrincipalId', async () => {
     const req = createCanonicalGuardianRequest({
       kind: 'tool_approval',
       sourceType: 'channel',
       conversationId: 'conv-1',
-      // No guardianExternalUserId — open request
+      guardianExternalUserId: 'guardian-1',
+      guardianPrincipalId: TEST_PRINCIPAL_ID,
       expiresAt: new Date(Date.now() + 60_000).toISOString(),
     });
 
     const result = await applyCanonicalGuardianDecision({
       requestId: req.id,
       action: 'approve_once',
-      actorContext: guardianActor({ externalUserId: 'anyone' }),
+      actorContext: guardianActor({ guardianPrincipalId: undefined }),
     });
 
     expect(result.applied).toBe(false);
@@ -276,6 +308,7 @@ describe('applyCanonicalGuardianDecision', () => {
       sourceType: 'channel',
       conversationId: 'conv-1',
       guardianExternalUserId: 'guardian-1',
+      guardianPrincipalId: TEST_PRINCIPAL_ID,
       expiresAt: new Date(Date.now() + 60_000).toISOString(),
     });
 
@@ -324,6 +357,7 @@ describe('applyCanonicalGuardianDecision', () => {
       sourceType: 'channel',
       conversationId: 'conv-1',
       guardianExternalUserId: 'guardian-1',
+      guardianPrincipalId: TEST_PRINCIPAL_ID,
       expiresAt: new Date(Date.now() + 60_000).toISOString(),
     });
 
@@ -351,6 +385,7 @@ describe('applyCanonicalGuardianDecision', () => {
       sourceChannel: 'telegram',
       conversationId: 'conv-1',
       guardianExternalUserId: 'guardian-1',
+      guardianPrincipalId: TEST_PRINCIPAL_ID,
       toolName: 'shell',
       inputDigest: 'sha256:abc',
       expiresAt: new Date(Date.now() + 60_000).toISOString(),
@@ -385,6 +420,7 @@ describe('applyCanonicalGuardianDecision', () => {
       sourceType: 'channel',
       conversationId: 'conv-1',
       guardianExternalUserId: 'guardian-1',
+      guardianPrincipalId: TEST_PRINCIPAL_ID,
       expiresAt: new Date(Date.now() - 10_000).toISOString(), // already expired
     });
 
@@ -405,6 +441,7 @@ describe('applyCanonicalGuardianDecision', () => {
       sourceType: 'channel',
       conversationId: 'conv-1',
       guardianExternalUserId: 'guardian-1',
+      guardianPrincipalId: TEST_PRINCIPAL_ID,
       // No expiresAt
     });
 
@@ -426,6 +463,7 @@ describe('applyCanonicalGuardianDecision', () => {
       sourceChannel: 'telegram',
       conversationId: 'conv-1',
       guardianExternalUserId: 'guardian-1',
+      guardianPrincipalId: TEST_PRINCIPAL_ID,
       toolName: 'file_read',
       inputDigest: 'sha256:def',
       expiresAt: new Date(Date.now() + 60_000).toISOString(),
@@ -446,6 +484,7 @@ describe('applyCanonicalGuardianDecision', () => {
       sourceType: 'voice',
       sourceChannel: 'twilio',
       guardianExternalUserId: 'guardian-1',
+      guardianPrincipalId: TEST_PRINCIPAL_ID,
       callSessionId: 'call-99',
       pendingQuestionId: 'pq-99',
       questionText: 'What is the password?',
@@ -464,12 +503,13 @@ describe('applyCanonicalGuardianDecision', () => {
     expect(resolved!.answerText).toBe('secret123');
   });
 
-  test('succeeds even with no resolver for unknown kind', async () => {
+  test('succeeds for non-decisionable kind with matching principal', async () => {
     const req = createCanonicalGuardianRequest({
       kind: 'unknown_kind',
       sourceType: 'channel',
       conversationId: 'conv-1',
       guardianExternalUserId: 'guardian-1',
+      guardianPrincipalId: TEST_PRINCIPAL_ID,
       expiresAt: new Date(Date.now() + 60_000).toISOString(),
     });
 
@@ -485,7 +525,7 @@ describe('applyCanonicalGuardianDecision', () => {
     expect(resolved!.status).toBe('approved');
   });
 
-  test('trusted desktop actor still mints scoped grant for approved canonical request', async () => {
+  test('desktop actor with matching principal mints scoped grant for approved canonical request', async () => {
     const req = createCanonicalGuardianRequest({
       kind: 'unknown_kind',
       sourceType: 'voice',
@@ -494,6 +534,7 @@ describe('applyCanonicalGuardianDecision', () => {
       callSessionId: 'call-voice-1',
       toolName: 'host_bash',
       inputDigest: 'sha256:voice-digest-1',
+      guardianPrincipalId: TEST_PRINCIPAL_ID,
       expiresAt: new Date(Date.now() + 60_000).toISOString(),
     });
 
@@ -530,6 +571,7 @@ describe('mintCanonicalRequestGrant', () => {
       sourceType: 'channel',
       sourceChannel: 'telegram',
       conversationId: 'conv-1',
+      guardianPrincipalId: TEST_PRINCIPAL_ID,
       toolName: 'shell',
       inputDigest: 'sha256:abc',
     });
@@ -549,6 +591,7 @@ describe('mintCanonicalRequestGrant', () => {
       sourceType: 'channel',
       sourceChannel: 'telegram',
       conversationId: 'conv-2',
+      guardianPrincipalId: TEST_PRINCIPAL_ID,
       toolName: 'shell',
       inputDigest: 'sha256:xyz',
     });
@@ -570,6 +613,7 @@ describe('mintCanonicalRequestGrant', () => {
     const req = createCanonicalGuardianRequest({
       kind: 'pending_question',
       sourceType: 'voice',
+      guardianPrincipalId: TEST_PRINCIPAL_ID,
       // No toolName or inputDigest
     });
 
@@ -586,6 +630,7 @@ describe('mintCanonicalRequestGrant', () => {
     const req = createCanonicalGuardianRequest({
       kind: 'tool_approval',
       sourceType: 'channel',
+      guardianPrincipalId: TEST_PRINCIPAL_ID,
       toolName: 'shell',
       // No inputDigest
     });

package/src/__tests__/guardian-grant-minting.test.ts

@@ -188,9 +188,9 @@ describe('guardian grant minting on tool-approval decisions', () => {
       conversationId: 'guardian-conv-1',
       callbackData: `apr:${requestId}:approve_once`,
       content: '',
-      externalChatId: GUARDIAN_CHAT,
+      conversationExternalId: GUARDIAN_CHAT,
       sourceChannel: 'telegram',
-      senderExternalUserId: GUARDIAN_USER,
+      actorExternalId: GUARDIAN_USER,
       replyCallbackUrl: 'https://gateway.test/deliver',
       guardianCtx: makeGuardianContext(),
       assistantId: ASSISTANT_ID,
@@ -236,9 +236,9 @@ describe('guardian grant minting on tool-approval decisions', () => {
       conversationId: 'guardian-conv-2',
       callbackData: `apr:${requestId}:approve_once`,
       content: '',
-      externalChatId: GUARDIAN_CHAT,
+      conversationExternalId: GUARDIAN_CHAT,
       sourceChannel: 'telegram',
-      senderExternalUserId: GUARDIAN_USER,
+      actorExternalId: GUARDIAN_USER,
       replyCallbackUrl: 'https://gateway.test/deliver',
       guardianCtx: makeGuardianContext(),
       assistantId: ASSISTANT_ID,
@@ -267,9 +267,9 @@ describe('guardian grant minting on tool-approval decisions', () => {
       conversationId: 'guardian-conv-2b',
       callbackData: `apr:${requestId}:approve_once`,
       content: '',
-      externalChatId: GUARDIAN_CHAT,
+      conversationExternalId: GUARDIAN_CHAT,
       sourceChannel: 'telegram',
-      senderExternalUserId: GUARDIAN_USER,
+      actorExternalId: GUARDIAN_USER,
       replyCallbackUrl: 'https://gateway.test/deliver',
       guardianCtx: makeGuardianContext(),
       assistantId: ASSISTANT_ID,
@@ -306,9 +306,9 @@ describe('guardian grant minting on tool-approval decisions', () => {
       conversationId: 'guardian-conv-3',
       callbackData: `apr:${requestId}:reject`,
       content: '',
-      externalChatId: GUARDIAN_CHAT,
+      conversationExternalId: GUARDIAN_CHAT,
       sourceChannel: 'telegram',
-      senderExternalUserId: GUARDIAN_USER,
+      actorExternalId: GUARDIAN_USER,
       replyCallbackUrl: 'https://gateway.test/deliver',
       guardianCtx: makeGuardianContext(),
       assistantId: ASSISTANT_ID,
@@ -335,9 +335,9 @@ describe('guardian grant minting on tool-approval decisions', () => {
       conversationId: 'guardian-conv-4',
       callbackData: `apr:${requestId}:approve_once`,
       content: '',
-      externalChatId: GUARDIAN_CHAT,
+      conversationExternalId: GUARDIAN_CHAT,
       sourceChannel: 'telegram',
-      senderExternalUserId: 'wrong-guardian-user',
+      actorExternalId: 'wrong-guardian-user',
       replyCallbackUrl: 'https://gateway.test/deliver',
       guardianCtx: makeGuardianContext(),
       assistantId: ASSISTANT_ID,
@@ -366,9 +366,9 @@ describe('guardian grant minting on tool-approval decisions', () => {
       conversationId: 'guardian-conv-5',
       callbackData: `apr:${requestId}:approve_once`,
       content: '',
-      externalChatId: GUARDIAN_CHAT,
+      conversationExternalId: GUARDIAN_CHAT,
       sourceChannel: 'telegram',
-      senderExternalUserId: GUARDIAN_USER,
+      actorExternalId: GUARDIAN_USER,
       replyCallbackUrl: 'https://gateway.test/deliver',
       guardianCtx: makeGuardianContext(),
       assistantId: ASSISTANT_ID,
@@ -400,9 +400,9 @@ describe('guardian grant minting on tool-approval decisions', () => {
     const result = await handleApprovalInterception({
       conversationId: 'guardian-conv-6',
       content: 'yes, approve it',
-      externalChatId: GUARDIAN_CHAT,
+      conversationExternalId: GUARDIAN_CHAT,
       sourceChannel: 'telegram',
-      senderExternalUserId: GUARDIAN_USER,
+      actorExternalId: GUARDIAN_USER,
       replyCallbackUrl: 'https://gateway.test/deliver',
       guardianCtx: makeGuardianContext(),
       assistantId: ASSISTANT_ID,
@@ -441,9 +441,9 @@ describe('guardian grant minting on tool-approval decisions', () => {
     const result = await handleApprovalInterception({
       conversationId: 'guardian-conv-7',
       content: 'no, deny it',
-      externalChatId: GUARDIAN_CHAT,
+      conversationExternalId: GUARDIAN_CHAT,
       sourceChannel: 'telegram',
-      senderExternalUserId: GUARDIAN_USER,
+      actorExternalId: GUARDIAN_USER,
       replyCallbackUrl: 'https://gateway.test/deliver',
       guardianCtx: makeGuardianContext(),
       assistantId: ASSISTANT_ID,
@@ -471,9 +471,9 @@ describe('guardian grant minting on tool-approval decisions', () => {
     const result = await handleApprovalInterception({
       conversationId: 'guardian-conv-8',
       content: 'yes',
-      externalChatId: GUARDIAN_CHAT,
+      conversationExternalId: GUARDIAN_CHAT,
       sourceChannel: 'telegram',
-      senderExternalUserId: GUARDIAN_USER,
+      actorExternalId: GUARDIAN_USER,
       replyCallbackUrl: 'https://gateway.test/deliver',
       guardianCtx: makeGuardianContext(),
       assistantId: ASSISTANT_ID,
@@ -507,9 +507,9 @@ describe('guardian grant minting on tool-approval decisions', () => {
       conversationId: 'guardian-conv-9',
       callbackData: `apr:${requestId}:approve_once`,
       content: '',
-      externalChatId: GUARDIAN_CHAT,
+      conversationExternalId: GUARDIAN_CHAT,
       sourceChannel: 'telegram',
-      senderExternalUserId: GUARDIAN_USER,
+      actorExternalId: GUARDIAN_USER,
       replyCallbackUrl: 'https://gateway.test/deliver',
       guardianCtx: makeGuardianContext(),
       assistantId: ASSISTANT_ID,
@@ -550,9 +550,9 @@ describe('approval interception trust-class regression coverage', () => {
     const result = await handleApprovalInterception({
       conversationId: CONVERSATION_ID,
       content: 'approve',
-      externalChatId: REQUESTER_CHAT,
+      conversationExternalId: REQUESTER_CHAT,
       sourceChannel: 'telegram',
-      senderExternalUserId: 'intruder-user-1',
+      actorExternalId: 'intruder-user-1',
       replyCallbackUrl: 'https://gateway.test/deliver',
       guardianCtx: {
         trustClass: 'unknown',
@@ -576,9 +576,9 @@ describe('approval interception trust-class regression coverage', () => {
     const result = await handleApprovalInterception({
       conversationId: CONVERSATION_ID,
       content: 'approve',
-      externalChatId: REQUESTER_CHAT,
+      conversationExternalId: REQUESTER_CHAT,
       sourceChannel: 'telegram',
-      senderExternalUserId: undefined,
+      actorExternalId: undefined,
       replyCallbackUrl: 'https://gateway.test/deliver',
       guardianCtx: {
         trustClass: 'unknown',

package/src/__tests__/guardian-principal-id-roundtrip.test.ts

@@ -0,0 +1,205 @@
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { afterAll, beforeEach, describe, expect, mock, test } from 'bun:test';
+
+const testDir = mkdtempSync(join(tmpdir(), 'guardian-principal-id-roundtrip-test-'));
+
+mock.module('../util/platform.js', () => ({
+  getDataDir: () => testDir,
+  isMacOS: () => process.platform === 'darwin',
+  isLinux: () => process.platform === 'linux',
+  isWindows: () => process.platform === 'win32',
+  getSocketPath: () => join(testDir, 'test.sock'),
+  getPidPath: () => join(testDir, 'test.pid'),
+  getDbPath: () => join(testDir, 'test.db'),
+  getLogPath: () => join(testDir, 'test.log'),
+  ensureDataDir: () => {},
+}));
+
+mock.module('../util/logger.js', () => ({
+  getLogger: () =>
+    new Proxy({} as Record<string, unknown>, {
+      get: () => () => {},
+    }),
+}));
+
+import {
+  createCanonicalGuardianRequest,
+  getCanonicalGuardianRequest,
+  resolveCanonicalGuardianRequest,
+  updateCanonicalGuardianRequest,
+} from '../memory/canonical-guardian-store.js';
+import { getDb, initializeDb, resetDb } from '../memory/db.js';
+import {
+  createBinding,
+  getActiveBinding,
+} from '../memory/guardian-bindings.js';
+
+initializeDb();
+
+function resetTables(): void {
+  const db = getDb();
+  db.run('DELETE FROM canonical_guardian_deliveries');
+  db.run('DELETE FROM canonical_guardian_requests');
+  db.run('DELETE FROM channel_guardian_bindings');
+}
+
+describe('guardianPrincipalId roundtrip', () => {
+  beforeEach(() => {
+    resetTables();
+  });
+
+  afterAll(() => {
+    resetDb();
+    try {
+      rmSync(testDir, { recursive: true });
+    } catch {
+      // best-effort cleanup
+    }
+  });
+
+  // ── channel_guardian_bindings ────────────────────────────────────────
+
+  describe('channel_guardian_bindings', () => {
+    test('creates binding with guardianPrincipalId and reads it back', () => {
+      const binding = createBinding({
+        assistantId: 'self',
+        channel: 'telegram',
+        guardianExternalUserId: 'tg-user-123',
+        guardianDeliveryChatId: 'tg-chat-123',
+        guardianPrincipalId: 'principal-abc-def',
+      });
+
+      expect(binding.guardianPrincipalId).toBe('principal-abc-def');
+
+      const fetched = getActiveBinding('self', 'telegram');
+      expect(fetched).not.toBeNull();
+      expect(fetched!.guardianPrincipalId).toBe('principal-abc-def');
+    });
+
+    test('creates binding without guardianPrincipalId (defaults to null)', () => {
+      const binding = createBinding({
+        assistantId: 'self',
+        channel: 'sms',
+        guardianExternalUserId: 'sms-user-456',
+        guardianDeliveryChatId: 'sms-chat-456',
+      });
+
+      expect(binding.guardianPrincipalId).toBeNull();
+
+      const fetched = getActiveBinding('self', 'sms');
+      expect(fetched).not.toBeNull();
+      expect(fetched!.guardianPrincipalId).toBeNull();
+    });
+  });
+
+  // ── canonical_guardian_requests ──────────────────────────────────────
+
+  describe('canonical_guardian_requests', () => {
+    test('creates request with guardianPrincipalId and reads it back', () => {
+      const req = createCanonicalGuardianRequest({
+        kind: 'tool_approval',
+        sourceType: 'channel',
+        sourceChannel: 'telegram',
+        guardianExternalUserId: 'guardian-tg-1',
+        guardianPrincipalId: 'principal-123',
+      });
+
+      expect(req.guardianPrincipalId).toBe('principal-123');
+      expect(req.decidedByPrincipalId).toBeNull();
+
+      const fetched = getCanonicalGuardianRequest(req.id);
+      expect(fetched).not.toBeNull();
+      expect(fetched!.guardianPrincipalId).toBe('principal-123');
+      expect(fetched!.decidedByPrincipalId).toBeNull();
+    });
+
+    test('access_request requires guardianPrincipalId (decisionable kind)', () => {
+      // access_request is now decisionable — creating one without a principal
+      // should throw IntegrityError.
+      expect(() => createCanonicalGuardianRequest({
+        kind: 'access_request',
+        sourceType: 'desktop',
+      })).toThrow('guardianPrincipalId');
+
+      // With a principal, creation succeeds
+      const req = createCanonicalGuardianRequest({
+        kind: 'access_request',
+        sourceType: 'desktop',
+        guardianPrincipalId: 'access-req-principal',
+      });
+      expect(req.guardianPrincipalId).toBe('access-req-principal');
+      expect(req.decidedByPrincipalId).toBeNull();
+    });
+
+    test('creates request with decidedByPrincipalId', () => {
+      const req = createCanonicalGuardianRequest({
+        kind: 'tool_approval',
+        sourceType: 'voice',
+        guardianPrincipalId: 'guardian-principal-1',
+        decidedByPrincipalId: 'decider-principal-1',
+      });
+
+      expect(req.decidedByPrincipalId).toBe('decider-principal-1');
+      expect(req.guardianPrincipalId).toBe('guardian-principal-1');
+    });
+
+    test('updates decidedByPrincipalId via updateCanonicalGuardianRequest', () => {
+      const req = createCanonicalGuardianRequest({
+        kind: 'tool_approval',
+        sourceType: 'channel',
+        guardianPrincipalId: 'principal-for-update-test',
+      });
+
+      const updated = updateCanonicalGuardianRequest(req.id, {
+        status: 'approved',
+        decidedByPrincipalId: 'principal-decider-abc',
+        decidedByExternalUserId: 'ext-user-1',
+      });
+
+      expect(updated).not.toBeNull();
+      expect(updated!.decidedByPrincipalId).toBe('principal-decider-abc');
+      expect(updated!.decidedByExternalUserId).toBe('ext-user-1');
+      expect(updated!.status).toBe('approved');
+    });
+
+    test('resolveCanonicalGuardianRequest writes decidedByPrincipalId', () => {
+      const req = createCanonicalGuardianRequest({
+        kind: 'tool_approval',
+        sourceType: 'voice',
+        guardianPrincipalId: 'guardian-principal-xyz',
+      });
+
+      const resolved = resolveCanonicalGuardianRequest(req.id, 'pending', {
+        status: 'approved',
+        answerText: 'Approved',
+        decidedByExternalUserId: 'guardian-ext-1',
+        decidedByPrincipalId: 'guardian-principal-xyz',
+      });
+
+      expect(resolved).not.toBeNull();
+      expect(resolved!.status).toBe('approved');
+      expect(resolved!.decidedByPrincipalId).toBe('guardian-principal-xyz');
+      expect(resolved!.decidedByExternalUserId).toBe('guardian-ext-1');
+      expect(resolved!.guardianPrincipalId).toBe('guardian-principal-xyz');
+    });
+
+    test('resolve without decidedByPrincipalId leaves it null', () => {
+      const req = createCanonicalGuardianRequest({
+        kind: 'tool_approval',
+        sourceType: 'channel',
+        guardianPrincipalId: 'principal-for-resolve-test',
+      });
+
+      const resolved = resolveCanonicalGuardianRequest(req.id, 'pending', {
+        status: 'denied',
+        decidedByExternalUserId: 'guardian-ext-2',
+      });
+
+      expect(resolved).not.toBeNull();
+      expect(resolved!.decidedByPrincipalId).toBeNull();
+    });
+  });
+});