@memberjunction/server 6.2.0-edge.0 → 6.2.0-edge.2

package/src/__tests__/newUsers.test.ts

@@ -168,7 +168,8 @@ vi.mock('@memberjunction/global', async (importOriginal) => {
     };
 });
 
-vi.mock('../auth/initializeProviders.js', () => ({ initializeAuthProviders: vi.fn() }));
+vi.mock('../auth/initializeProviders.js', () => ({ InitializeAuthProviders: vi.fn(),
+    get initializeAuthProviders() { return this.InitializeAuthProviders; } }));
 
 vi.mock('@memberjunction/auth-providers', () => ({
     AuthProviderFactory: {
@@ -195,7 +196,7 @@ vi.mock('@memberjunction/api-keys', () => ({
 
 // ─── Import after mocks ─────────────────────────────────────────────────────
 import { NewUserBase } from '../auth/newUsers.js';
-import { verifyUserRecord } from '../auth/index.js';
+import { VerifyUserRecord } from '../auth/index.js';
 
 // ─── Mock-entity plumbing ───────────────────────────────────────────────────
 
@@ -557,7 +558,7 @@ describe('verifyUserRecord', () => {
     }
 
     it('returns undefined when no email is supplied', async () => {
-        const user = await verifyUserRecord(undefined, 'A', 'B');
+        const user = await VerifyUserRecord(undefined, 'A', 'B');
 
         expect(user).toBeUndefined();
         expect(mockGetEntityObject).not.toHaveBeenCalled();
@@ -566,7 +567,7 @@ describe('verifyUserRecord', () => {
     it('returns the cached user, matching email case-insensitively and trimmed', async () => {
         addCacheUser('someone@example.com');
 
-        const user = await verifyUserRecord('  SomeOne@Example.COM  ', 'A', 'B');
+        const user = await VerifyUserRecord('  SomeOne@Example.COM  ', 'A', 'B');
 
         expect(user).toBeDefined();
         expect((user as unknown as { Email: string }).Email).toBe('someone@example.com');
@@ -577,7 +578,7 @@ describe('verifyUserRecord', () => {
         mockCacheUsers.push({ ID: 'broken-1', Name: 'Broken', Email: '  ', Type: 'User' });
         const errorSpy = vi.spyOn(console, 'error').mockImplementation(() => undefined);
 
-        const user = await verifyUserRecord('missing@example.com', undefined, undefined);
+        const user = await VerifyUserRecord('missing@example.com', undefined, undefined);
 
         expect(user).toBeUndefined();
         expect(errorSpy).toHaveBeenCalledWith(expect.stringContaining('broken-1'));
@@ -587,15 +588,15 @@ describe('verifyUserRecord', () => {
         it('does NOT create a user when autoCreateNewUsers is false', async () => {
             mockConfig.userHandling.autoCreateNewUsers = false;
 
-            const user = await verifyUserRecord('new@example.com', 'New', 'User');
+            const user = await VerifyUserRecord('new@example.com', 'New', 'User');
 
             expect(user).toBeUndefined();
             expect(mockGetEntityObject).not.toHaveBeenCalled();
         });
 
         it('does NOT create a user when firstName or lastName is missing', async () => {
-            const missingFirst = await verifyUserRecord('new@example.com', undefined, 'User');
-            const missingLast = await verifyUserRecord('new@example.com', 'New', undefined);
+            const missingFirst = await VerifyUserRecord('new@example.com', undefined, 'User');
+            const missingLast = await VerifyUserRecord('new@example.com', 'New', undefined);
 
             expect(missingFirst).toBeUndefined();
             expect(missingLast).toBeUndefined();
@@ -605,7 +606,7 @@ describe('verifyUserRecord', () => {
         it('creates the user when enabled and domains are unrestricted, stamping config roles onto the returned UserInfo', async () => {
             mockConfig.userHandling.newUserRoles = ['UI', 'Developer'];
 
-            const user = await verifyUserRecord('new@example.com', 'New', 'User');
+            const user = await VerifyUserRecord('new@example.com', 'New', 'User');
 
             expect(user).toBeDefined();
             const stamped = user as unknown as { Email: string; UserRoles: Array<{ Role: string; RoleID: string; UserID: string }> };
@@ -621,7 +622,7 @@ describe('verifyUserRecord', () => {
         it('returns undefined when the underlying createNewUser fails', async () => {
             saveBehavior['MJ: Users'] = () => false;
 
-            const user = await verifyUserRecord('new@example.com', 'New', 'User');
+            const user = await VerifyUserRecord('new@example.com', 'New', 'User');
 
             expect(user).toBeUndefined();
             // The cache is no longer empty at rest (it holds the configured context user), so
@@ -637,35 +638,35 @@ describe('verifyUserRecord', () => {
         });
 
         it('creates the user when the email domain is authorized', async () => {
-            const user = await verifyUserRecord('new@example.com', 'New', 'User');
+            const user = await VerifyUserRecord('new@example.com', 'New', 'User');
 
             expect(user).toBeDefined();
             expect(entitiesOf('MJ: Users')).toHaveLength(1);
         });
 
         it('does NOT create when the email domain is not authorized', async () => {
-            const user = await verifyUserRecord('new@evil.com', 'New', 'User');
+            const user = await VerifyUserRecord('new@evil.com', 'New', 'User');
 
             expect(user).toBeUndefined();
             expect(mockGetEntityObject).not.toHaveBeenCalled();
         });
 
         it('creates when restricted and no request Origin is supplied, if the email domain is authorized', async () => {
-            const user = await verifyUserRecord('new@example.com', 'New', 'User', undefined);
+            const user = await VerifyUserRecord('new@example.com', 'New', 'User', undefined);
 
             expect(user).toBeDefined();
             expect(entitiesOf('MJ: Users')).toHaveLength(1);
         });
 
         it('does NOT create when a forged Origin is authorized but the email domain is not', async () => {
-            const user = await verifyUserRecord('new@evil.com', 'New', 'User', 'example.com');
+            const user = await VerifyUserRecord('new@evil.com', 'New', 'User', 'example.com');
 
             expect(user).toBeUndefined();
             expect(mockGetEntityObject).not.toHaveBeenCalled();
         });
 
         it('matches email domains case-insensitively', async () => {
-            const user = await verifyUserRecord('new@EXAMPLE.COM', 'New', 'User');
+            const user = await VerifyUserRecord('new@EXAMPLE.COM', 'New', 'User');
 
             expect(user).toBeDefined();
         });
@@ -673,7 +674,7 @@ describe('verifyUserRecord', () => {
         it('supports wildcard patterns for email subdomains', async () => {
             mockConfig.userHandling.newUserAuthorizedDomains = ['*.example.com'];
 
-            const user = await verifyUserRecord('new@mail.example.com', 'New', 'User');
+            const user = await VerifyUserRecord('new@mail.example.com', 'New', 'User');
 
             expect(user).toBeDefined();
         });
@@ -681,7 +682,7 @@ describe('verifyUserRecord', () => {
         it('does NOT match the apex against "*.example.com" (pattern is matched in full)', async () => {
             mockConfig.userHandling.newUserAuthorizedDomains = ['*.example.com'];
 
-            const user = await verifyUserRecord('new@example.com', 'New', 'User');
+            const user = await VerifyUserRecord('new@example.com', 'New', 'User');
 
             expect(user).toBeUndefined();
             expect(mockGetEntityObject).not.toHaveBeenCalled();
@@ -690,27 +691,27 @@ describe('verifyUserRecord', () => {
         it('rejects prefix confusion: "*.example.com" does not match "evilexample.com" (dot is escaped)', async () => {
             mockConfig.userHandling.newUserAuthorizedDomains = ['*.example.com'];
 
-            const user = await verifyUserRecord('new@evilexample.com', 'New', 'User');
+            const user = await VerifyUserRecord('new@evilexample.com', 'New', 'User');
 
             expect(user).toBeUndefined();
             expect(mockGetEntityObject).not.toHaveBeenCalled();
         });
 
         it('rejects suffix confusion: the pattern is anchored, so "example.com.evil.com" is not authorized', async () => {
-            const user = await verifyUserRecord('new@example.com.evil.com', 'New', 'User');
+            const user = await VerifyUserRecord('new@example.com.evil.com', 'New', 'User');
 
             expect(user).toBeUndefined();
             expect(mockGetEntityObject).not.toHaveBeenCalled();
         });
 
         it('rejects "evilexample.com" against the plain "example.com" pattern (anchored at both ends)', async () => {
-            const user = await verifyUserRecord('x@evilexample.com', 'New', 'User');
+            const user = await VerifyUserRecord('x@evilexample.com', 'New', 'User');
 
             expect(user).toBeUndefined();
         });
 
         it('does NOT create when the identity has no email domain (username-only IdP)', async () => {
-            const user = await verifyUserRecord('bare-username', 'New', 'User');
+            const user = await VerifyUserRecord('bare-username', 'New', 'User');
 
             expect(user).toBeUndefined();
             expect(mockGetEntityObject).not.toHaveBeenCalled();
@@ -727,7 +728,7 @@ describe('verifyUserRecord', () => {
             });
             const dataSource = {} as unknown as import('mssql').ConnectionPool;
 
-            const user = await verifyUserRecord('late@example.com', undefined, undefined, undefined, dataSource);
+            const user = await VerifyUserRecord('late@example.com', undefined, undefined, undefined, dataSource);
 
             expect(user).toBeDefined();
             expect((user as unknown as { Email: string }).Email).toBe('late@example.com');
@@ -739,7 +740,7 @@ describe('verifyUserRecord', () => {
             mockConfig.userHandling.updateCacheWhenNotFound = true;
             const dataSource = {} as unknown as import('mssql').ConnectionPool;
 
-            const user = await verifyUserRecord('never@example.com', undefined, undefined, undefined, dataSource);
+            const user = await VerifyUserRecord('never@example.com', undefined, undefined, undefined, dataSource);
 
             expect(user).toBeUndefined();
             expect(mockRefresh).toHaveBeenCalledTimes(1);

package/src/__tests__/orphanedConversationDetailReconciler.test.ts

@@ -0,0 +1,283 @@
+/**
+ * Conversation details left behind by a finished run must be closed (MJ #4222).
+ *
+ * `AgentRunner` closes the detail as the last step of a run, so a process that dies mid-run never
+ * gets there. The agent-run watchdog repairs the RUN but nothing repaired the detail — and the
+ * detail is the row the chat renders from. Observed directly: run B3E67FE3 force-failed by the
+ * watchdog while its detail stayed `In-Progress`, spinning for anyone who opened it.
+ *
+ * The properties that keep this safe to run unattended are pinned here: it never closes a message
+ * whose work is still going, and it never races the normal completion path.
+ */
+import 'reflect-metadata';
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import type { RunViewParams, UserInfo } from '@memberjunction/core';
+
+const { mockRunView } = vi.hoisted(() => ({ mockRunView: vi.fn() }));
+
+const { mockGetEntityObject, writableStore } = vi.hoisted(() => ({
+    mockGetEntityObject: vi.fn(),
+    writableStore: { last: null as Record<string, unknown> | null },
+}));
+
+vi.mock('@memberjunction/global', () => ({
+    UUIDsEqual: (a: string, b: string) => String(a).toLowerCase() === String(b).toLowerCase(),
+}));
+
+vi.mock('@memberjunction/sqlserver-dataprovider', () => ({
+    UserCache: { Instance: { Users: [{ ID: 'OWNER-1', Email: 'owner@example.com' }] } },
+}));
+
+vi.mock('@memberjunction/core', () => {
+    class MockRunView {
+        public static FromMetadataProvider(): MockRunView {
+            return new MockRunView();
+        }
+        public async RunView(...args: unknown[]): Promise<unknown> {
+            return mockRunView(...args);
+        }
+    }
+    return { LogError: vi.fn(), LogStatus: vi.fn(), RunView: MockRunView };
+});
+
+import { ReconcileOrphanedConversationDetails, ORPHAN_DETAIL_GRACE_MS } from '../generic/OrphanedConversationDetailReconciler.js';
+
+const USER = { ID: 'U1' } as unknown as UserInfo;
+const CONVERSATION_ID = 'C1';
+
+/**
+ * Provider stub: hands back the entity the reconciler actually writes through, and quotes names the
+ * way the SQL Server provider does.
+ */
+const PROVIDER = {
+    GetEntityObject: mockGetEntityObject,
+    EntityByName: (name: string) =>
+        name === 'MJ: AI Agent Runs' ? { SchemaName: '__mj', BaseView: 'vwAIAgentRuns' } : undefined,
+    QuoteIdentifier: (name: string) => `[${name}]`,
+    QuoteSchemaAndView: (schema: string, view: string) => `[${schema}].[${view}]`,
+} as never;
+const DETAIL_ID = 'D1';
+
+function detail(over: Record<string, unknown> = {}) {
+    return { ID: DETAIL_ID, ConversationID: CONVERSATION_ID, Status: 'In-Progress', Message: '', ...over };
+}
+
+/**
+ * The record the reconciler loads and saves. Separate from the RunView projection on purpose: the
+ * reconciler deliberately does NOT write the entity RunView returned, because that one carries the
+ * system user and the conversation-detail permission gate refuses a non-owner.
+ */
+function writable(saveResult = true, loadedStatus = 'In-Progress') {
+    const w = {
+        ID: DETAIL_ID,
+        Status: loadedStatus,
+        Message: '',
+        Load: vi.fn(async () => true),
+        Save: vi.fn(async () => saveResult),
+        LatestResult: { CompleteMessage: 'denied' },
+    };
+    writableStore.last = w;
+    return w;
+}
+
+function script(details: unknown[], runs: unknown[], ownerId: string | null = 'OWNER-1', loadedStatus = 'In-Progress') {
+    mockRunView.mockImplementation(async (...args: unknown[]) => {
+        const params = args[0] as RunViewParams | undefined;
+        if (!params) throw new Error('RunView called with no params');
+        if (params.EntityName === 'MJ: Conversation Details') return { Success: true, Results: details };
+        if (params.EntityName === 'MJ: AI Agent Runs') return { Success: true, Results: runs };
+        if (params.EntityName === 'MJ: Conversations') {
+            return { Success: true, Results: ownerId ? [{ ID: CONVERSATION_ID, UserID: ownerId }] : [] };
+        }
+        throw new Error(`unexpected entity ${params.EntityName}`);
+    });
+    mockGetEntityObject.mockImplementation(async () => writable(true, loadedStatus));
+}
+
+const longAgo = () => new Date(Date.now() - ORPHAN_DETAIL_GRACE_MS - 60_000).toISOString();
+const justNow = () => new Date().toISOString();
+
+describe('ReconcileOrphanedConversationDetails', () => {
+    // Block body, NOT a concise arrow: `mockReset()` returns the mock, which is callable, and
+    // vitest treats a function returned from beforeEach as a teardown hook — so a concise arrow
+    // hands vitest the mock itself to invoke with no arguments after every test.
+    beforeEach(() => {
+        mockRunView.mockReset();
+        mockGetEntityObject.mockReset();
+        writableStore.last = null;
+    });
+
+    it('closes a detail whose run failed long ago', async () => {
+        const d = detail();
+        script([d], [{ ConversationDetailID: DETAIL_ID, Status: 'Failed', CompletedAt: longAgo(), ErrorMessage: 'watchdog force-fail' }]);
+
+        const closed = await ReconcileOrphanedConversationDetails(PROVIDER, USER);
+
+        expect(closed).toBe(1);
+        expect(writableStore.last?.Status).toBe('Error');
+        expect(writableStore.last?.Message).toBe('watchdog force-fail');
+    });
+
+    it('falls back to a failure marker only when the failed run carries no error text', async () => {
+        script([detail()], [{ ConversationDetailID: DETAIL_ID, Status: 'Failed', CompletedAt: longAgo() }]);
+
+        await ReconcileOrphanedConversationDetails(PROVIDER, USER);
+
+        expect(writableStore.last?.Status).toBe('Error');
+        expect(writableStore.last?.Message).toBe('❌ Failed');
+    });
+
+    it('marks a completed run as Complete, not Error', async () => {
+        const d = detail();
+        script([d], [{ ConversationDetailID: DETAIL_ID, Status: 'Completed', CompletedAt: longAgo() }]);
+
+        await ReconcileOrphanedConversationDetails(PROVIDER, USER);
+
+        expect(writableStore.last?.Status).toBe('Complete');
+        // A successful run has no error to report, so an empty message stays empty rather than
+        // carrying a failure marker that contradicts the status beside it.
+        expect(writableStore.last?.Message).toBe('');
+    });
+
+    it('marks a run that ended awaiting the user\'s reply as Complete', async () => {
+        // AwaitingFeedback is how a normal chat turn ends: the run succeeded and the agent's
+        // reply is the message. A process that dies before closing the detail leaves exactly
+        // this pair behind, and the stale-run sweep never touches it because it is not Running.
+        script([detail()], [{ ConversationDetailID: DETAIL_ID, Status: 'AwaitingFeedback', CompletedAt: longAgo() }]);
+
+        expect(await ReconcileOrphanedConversationDetails(PROVIDER, USER)).toBe(1);
+        expect(writableStore.last?.Status).toBe('Complete');
+        expect(writableStore.last?.Message).toBe('');
+    });
+
+    it('leaves a message alone while its run is parked on a workflow', async () => {
+        // Paused means a task graph is still executing on the run's behalf.
+        script([detail()], [{ ConversationDetailID: DETAIL_ID, Status: 'Paused', CompletedAt: null }]);
+
+        expect(await ReconcileOrphanedConversationDetails(PROVIDER, USER)).toBe(0);
+        expect(mockGetEntityObject).not.toHaveBeenCalled();
+    });
+
+    it('leaves a message alone while its run is still executing', async () => {
+        const d = detail();
+        script([d], [{ ConversationDetailID: DETAIL_ID, Status: 'Running', CompletedAt: null }]);
+
+        expect(await ReconcileOrphanedConversationDetails(PROVIDER, USER)).toBe(0);
+        expect(mockGetEntityObject).not.toHaveBeenCalled();
+    });
+
+    it('does not race the normal completion path inside the grace window', async () => {
+        const d = detail();
+        script([d], [{ ConversationDetailID: DETAIL_ID, Status: 'Completed', CompletedAt: justNow() }]);
+
+        expect(await ReconcileOrphanedConversationDetails(PROVIDER, USER)).toBe(0);
+        expect(mockGetEntityObject).not.toHaveBeenCalled();
+    });
+
+    it('leaves a message alone when no run exists yet', async () => {
+        const d = detail();
+        script([d], []);
+
+        expect(await ReconcileOrphanedConversationDetails(PROVIDER, USER)).toBe(0);
+        expect(mockGetEntityObject).not.toHaveBeenCalled();
+    });
+
+    it('judges a retried message on its newest attempt, not an older finished one', async () => {
+        const d = detail();
+        // DESC order: newest first. The newest attempt is still running.
+        script([d], [
+            { ConversationDetailID: DETAIL_ID, Status: 'Running', CompletedAt: null },
+            { ConversationDetailID: DETAIL_ID, Status: 'Failed', CompletedAt: longAgo() },
+        ]);
+
+        expect(await ReconcileOrphanedConversationDetails(PROVIDER, USER)).toBe(0);
+    });
+
+    it('preserves an existing message rather than overwriting the answer', async () => {
+        script([detail()], [{ ConversationDetailID: DETAIL_ID, Status: 'Completed', CompletedAt: longAgo() }]);
+        mockGetEntityObject.mockImplementation(async () => {
+            const w = writable();
+            w.Message = 'the real answer';
+            return w;
+        });
+
+        await ReconcileOrphanedConversationDetails(PROVIDER, USER);
+
+        // The loaded record already carries the answer; only the status should change.
+        expect(writableStore.last?.Message).toBe('the real answer');
+        expect(writableStore.last?.Status).toBe('Complete');
+    });
+
+    it('reports a refused save without throwing', async () => {
+        script([detail()], [{ ConversationDetailID: DETAIL_ID, Status: 'Failed', CompletedAt: longAgo() }]);
+        mockGetEntityObject.mockImplementation(async () => writable(false));
+
+        expect(await ReconcileOrphanedConversationDetails(PROVIDER, USER)).toBe(0);
+    });
+
+    it('writes as the conversation OWNER, never as the calling system user', async () => {
+        // REGRESSION, found only by running it against real data. The permission gate on
+        // MJ: Conversation Details refuses a non-owner and returns false with NO LatestResult, so
+        // every save was silently rejected while the reconciler reported success-shaped logs. The
+        // system user this pass runs as owns nothing, which is exactly who that gate stops.
+        script([detail()], [{ ConversationDetailID: DETAIL_ID, Status: 'Failed', CompletedAt: longAgo() }]);
+
+        await ReconcileOrphanedConversationDetails(PROVIDER, USER);
+
+        expect(mockGetEntityObject).toHaveBeenCalledWith(
+            'MJ: Conversation Details',
+            expect.objectContaining({ ID: 'OWNER-1' })
+        );
+    });
+
+    it('leaves the detail alone when no owner can be resolved', async () => {
+        script([detail()], [{ ConversationDetailID: DETAIL_ID, Status: 'Failed', CompletedAt: longAgo() }], null);
+
+        expect(await ReconcileOrphanedConversationDetails(PROVIDER, USER)).toBe(0);
+        expect(mockGetEntityObject).not.toHaveBeenCalled();
+    });
+
+    it('never throws out of a maintenance pass', async () => {
+        mockRunView.mockImplementation(async () => { throw new Error('db down'); });
+
+        await expect(ReconcileOrphanedConversationDetails(PROVIDER, USER)).resolves.toBe(0);
+    });
+
+    it('asks only for details that have a finished run, so stuck rows cannot fill the window', async () => {
+        // Details with no run, or with a run still executing, are never closed here. Read without
+        // this filter, 200 of them pin the oldest-first window and no closable orphan is reached.
+        script([detail()], [{ ConversationDetailID: DETAIL_ID, Status: 'Failed', CompletedAt: longAgo() }]);
+
+        await ReconcileOrphanedConversationDetails(PROVIDER, USER);
+
+        const detailCall = mockRunView.mock.calls.find(
+            c => (c[0] as RunViewParams).EntityName === 'MJ: Conversation Details'
+        );
+        expect((detailCall?.[0] as RunViewParams).ExtraFilter).toBe(
+            "Status = 'In-Progress' AND Role = 'AI' AND ID IN (SELECT [ConversationDetailID] FROM [__mj].[vwAIAgentRuns] " +
+            "WHERE [Status] IN ('Completed','AwaitingFeedback','Failed','Cancelled'))"
+        );
+    });
+
+    it('leaves a detail alone when something else closed it after the list query', async () => {
+        // The normal completion path can close the row between our read and our write. Writing
+        // anyway would stamp this pass's outcome over the one that actually happened.
+        script(
+            [detail()],
+            [{ ConversationDetailID: DETAIL_ID, Status: 'Failed', CompletedAt: longAgo(), ErrorMessage: 'late' }],
+            'OWNER-1',
+            'Complete'
+        );
+
+        const closed = await ReconcileOrphanedConversationDetails(PROVIDER, USER);
+
+        expect(closed).toBe(0);
+        expect(writableStore.last?.Status).toBe('Complete');
+        expect((writableStore.last?.Save as ReturnType<typeof vi.fn>)).not.toHaveBeenCalled();
+    });
+
+    it('does nothing when no message is in progress', async () => {
+        script([], []);
+        expect(await ReconcileOrphanedConversationDetails(PROVIDER, USER)).toBe(0);
+    });
+});

package/src/__tests__/principals.test.ts

@@ -13,7 +13,7 @@
  * singleton nor a database — the seam is `(candidate, users) -> resolution`.
  */
 import { describe, it, expect } from 'vitest';
-import { resolvePrincipalFrom, type ResolvablePrincipal } from '../auth/principals.js';
+import { ResolvePrincipalFrom, type ResolvablePrincipal } from '../auth/principals.js';
 
 /**
  * The system user's ID, pinned by `UserCache` (`SYSTEM_USER_ID`) and seeded by every baseline.
@@ -63,14 +63,14 @@ const STOCK_HOST: ResolvablePrincipal[] = [SYSTEM, ANONYMOUS, HOST_ADMIN];
 describe('resolvePrincipalFrom', () => {
     describe('the shipped default (#4209)', () => {
         it('resolves the email-shaped default to the seeded System user', () => {
-            const result = resolvePrincipalFrom(SHIPPED_DEFAULT, STOCK_HOST, SYSTEM_USER_ID);
+            const result = ResolvePrincipalFrom(SHIPPED_DEFAULT, STOCK_HOST, SYSTEM_USER_ID);
 
             expect(result.user).toBe(SYSTEM);
             expect(result.reason).toBe('email');
         });
 
         it('reports no warning when the default resolves, so a stock host logs nothing', () => {
-            const result = resolvePrincipalFrom(SHIPPED_DEFAULT, STOCK_HOST, SYSTEM_USER_ID);
+            const result = ResolvePrincipalFrom(SHIPPED_DEFAULT, STOCK_HOST, SYSTEM_USER_ID);
 
             expect(result.warning).toBeUndefined();
         });
@@ -81,8 +81,8 @@ describe('resolvePrincipalFrom', () => {
             // `SELECT * FROM vwUsers` carries no ORDER BY and the cache is mutated in place at
             // runtime, so row order differs between boots AND within a process. Attribution must
             // not depend on it: this is what made CreatedByUserID incidental.
-            const ordered = resolvePrincipalFrom(SHIPPED_DEFAULT, STOCK_HOST, SYSTEM_USER_ID);
-            const reversed = resolvePrincipalFrom(SHIPPED_DEFAULT, [...STOCK_HOST].reverse(), SYSTEM_USER_ID);
+            const ordered = ResolvePrincipalFrom(SHIPPED_DEFAULT, STOCK_HOST, SYSTEM_USER_ID);
+            const reversed = ResolvePrincipalFrom(SHIPPED_DEFAULT, [...STOCK_HOST].reverse(), SYSTEM_USER_ID);
 
             expect(reversed.user).toBe(ordered.user);
         });
@@ -107,7 +107,7 @@ describe('resolvePrincipalFrom', () => {
                 IsActive: true,
             };
 
-            const result = resolvePrincipalFrom('support@acme.com', [emailSupport, namedSupport], SYSTEM_USER_ID);
+            const result = ResolvePrincipalFrom('support@acme.com', [emailSupport, namedSupport], SYSTEM_USER_ID);
 
             expect(result.user).toBe(namedSupport);
             expect(result.reason).toBe('name');
@@ -125,15 +125,15 @@ describe('resolvePrincipalFrom', () => {
         const HIGH: ResolvablePrincipal = { ID: 'FFFFFFFF-0000-0000-0000-00000000000F', Name: 'shared.name', Email: 'high@acme.com', Type: 'User', IsActive: true };
 
         it('picks the lowest-ID user when two users share the configured Name', () => {
-            const result = resolvePrincipalFrom('shared.name', [HIGH, LOW, SYSTEM], SYSTEM_USER_ID);
+            const result = ResolvePrincipalFrom('shared.name', [HIGH, LOW, SYSTEM], SYSTEM_USER_ID);
 
             expect(result.user).toBe(LOW);
             expect(result.reason).toBe('name');
         });
 
         it('resolves a duplicated Name identically however the cache is ordered', () => {
-            const forward = resolvePrincipalFrom('shared.name', [HIGH, LOW, SYSTEM], SYSTEM_USER_ID);
-            const reversed = resolvePrincipalFrom('shared.name', [SYSTEM, LOW, HIGH], SYSTEM_USER_ID);
+            const forward = ResolvePrincipalFrom('shared.name', [HIGH, LOW, SYSTEM], SYSTEM_USER_ID);
+            const reversed = ResolvePrincipalFrom('shared.name', [SYSTEM, LOW, HIGH], SYSTEM_USER_ID);
 
             expect(reversed.user).toBe(forward.user);
         });
@@ -145,7 +145,7 @@ describe('resolvePrincipalFrom', () => {
             const lowEmail: ResolvablePrincipal = { ...LOW, Name: 'a.person', Email: 'shared@acme.com' };
             const highEmail: ResolvablePrincipal = { ...HIGH, Name: 'b.person', Email: 'shared@acme.com' };
 
-            const result = resolvePrincipalFrom('shared@acme.com', [highEmail, lowEmail, SYSTEM], SYSTEM_USER_ID);
+            const result = ResolvePrincipalFrom('shared@acme.com', [highEmail, lowEmail, SYSTEM], SYSTEM_USER_ID);
 
             expect(result.user).toBe(lowEmail);
             expect(result.reason).toBe('email');
@@ -169,7 +169,7 @@ describe('resolvePrincipalFrom', () => {
         };
 
         it('does not resolve a deactivated candidate by Email', () => {
-            const result = resolvePrincipalFrom('departed@acme.com', [...STOCK_HOST, RETIRED], SYSTEM_USER_ID);
+            const result = ResolvePrincipalFrom('departed@acme.com', [...STOCK_HOST, RETIRED], SYSTEM_USER_ID);
 
             expect(result.user).toBe(SYSTEM);
             expect(result.reason).toBe('system');
@@ -180,14 +180,14 @@ describe('resolvePrincipalFrom', () => {
             // most: without it the guarantee holds only for the rungs nobody configures.
             const renamed: ResolvablePrincipal = { ...RETIRED, Name: 'ops-service-account', Email: 'ops@acme.com' };
 
-            const result = resolvePrincipalFrom('ops-service-account', [...STOCK_HOST, renamed], SYSTEM_USER_ID);
+            const result = ResolvePrincipalFrom('ops-service-account', [...STOCK_HOST, renamed], SYSTEM_USER_ID);
 
             expect(result.user).toBe(SYSTEM);
             expect(result.reason).toBe('system');
         });
 
         it('reports that the candidate matched but is inactive, not that it matched nothing', () => {
-            const result = resolvePrincipalFrom('departed@acme.com', [...STOCK_HOST, RETIRED], SYSTEM_USER_ID);
+            const result = ResolvePrincipalFrom('departed@acme.com', [...STOCK_HOST, RETIRED], SYSTEM_USER_ID);
 
             // "matched no user's Name or Email" would send the operator hunting for a typo in a
             // value that is spelled correctly. The fix here is to reactivate the account or name a
@@ -215,7 +215,7 @@ describe('resolvePrincipalFrom', () => {
                 IsActive: true,
             };
 
-            const result = resolvePrincipalFrom('ops@acme.com', [inactiveByName, activeByEmail], SYSTEM_USER_ID);
+            const result = ResolvePrincipalFrom('ops@acme.com', [inactiveByName, activeByEmail], SYSTEM_USER_ID);
 
             expect(result.user).toBe(activeByEmail);
             expect(result.reason).toBe('email');
@@ -224,14 +224,14 @@ describe('resolvePrincipalFrom', () => {
     });
     describe('fallbacks', () => {
         it('falls back to the System user rather than an arbitrary Owner when the candidate is unresolvable', () => {
-            const result = resolvePrincipalFrom('nobody@nowhere.example', STOCK_HOST, SYSTEM_USER_ID);
+            const result = ResolvePrincipalFrom('nobody@nowhere.example', STOCK_HOST, SYSTEM_USER_ID);
 
             expect(result.user).toBe(SYSTEM);
             expect(result.reason).toBe('system');
         });
 
         it('warns when a configured candidate did not resolve, naming the candidate', () => {
-            const result = resolvePrincipalFrom('nobody@nowhere.example', STOCK_HOST, SYSTEM_USER_ID);
+            const result = ResolvePrincipalFrom('nobody@nowhere.example', STOCK_HOST, SYSTEM_USER_ID);
 
             expect(result.warning).toContain('nobody@nowhere.example');
         });
@@ -239,7 +239,7 @@ describe('resolvePrincipalFrom', () => {
         it('falls back to the System user WITHOUT warning when no candidate is configured', () => {
             // Zod defaults this setting to '', so an unset/blank value must not be reported as a
             // misconfiguration — but it must still land somewhere deterministic.
-            const result = resolvePrincipalFrom('', STOCK_HOST, SYSTEM_USER_ID);
+            const result = ResolvePrincipalFrom('', STOCK_HOST, SYSTEM_USER_ID);
 
             expect(result.user).toBe(SYSTEM);
             expect(result.warning).toBeUndefined();
@@ -256,7 +256,7 @@ describe('resolvePrincipalFrom', () => {
             };
             const users = [laterOwner, HOST_ADMIN, ANONYMOUS];
 
-            const result = resolvePrincipalFrom('nobody@nowhere.example', users, SYSTEM_USER_ID);
+            const result = ResolvePrincipalFrom('nobody@nowhere.example', users, SYSTEM_USER_ID);
 
             expect(result.user).toBe(HOST_ADMIN);
             expect(result.reason).toBe('owner');
@@ -271,7 +271,7 @@ describe('resolvePrincipalFrom', () => {
                 IsActive: false,
             };
 
-            const result = resolvePrincipalFrom('nobody@nowhere.example', [inactiveOwner, HOST_ADMIN], SYSTEM_USER_ID);
+            const result = ResolvePrincipalFrom('nobody@nowhere.example', [inactiveOwner, HOST_ADMIN], SYSTEM_USER_ID);
 
             expect(result.user).toBe(HOST_ADMIN);
         });
@@ -281,7 +281,7 @@ describe('resolvePrincipalFrom', () => {
             // "we never act as a disabled user, except as the one user we reach first".
             const inactiveSystem: ResolvablePrincipal = { ...SYSTEM, IsActive: false };
 
-            const result = resolvePrincipalFrom('nobody@nowhere.example', [inactiveSystem, HOST_ADMIN], SYSTEM_USER_ID);
+            const result = ResolvePrincipalFrom('nobody@nowhere.example', [inactiveSystem, HOST_ADMIN], SYSTEM_USER_ID);
 
             expect(result.user).toBe(HOST_ADMIN);
             expect(result.reason).toBe('owner');
@@ -290,13 +290,13 @@ describe('resolvePrincipalFrom', () => {
         it('returns no principal when the system user is deactivated and no active Owner remains', () => {
             const inactiveSystem: ResolvablePrincipal = { ...SYSTEM, IsActive: false };
 
-            const result = resolvePrincipalFrom('nobody@nowhere.example', [inactiveSystem, ANONYMOUS], SYSTEM_USER_ID);
+            const result = ResolvePrincipalFrom('nobody@nowhere.example', [inactiveSystem, ANONYMOUS], SYSTEM_USER_ID);
 
             expect(result.user).toBeNull();
         });
 
         it('returns no principal at all when the cache is empty', () => {
-            const result = resolvePrincipalFrom(SHIPPED_DEFAULT, [], SYSTEM_USER_ID);
+            const result = ResolvePrincipalFrom(SHIPPED_DEFAULT, [], SYSTEM_USER_ID);
 
             expect(result.user).toBeNull();
             expect(result.reason).toBe('none');