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

package/src/__tests__/newUsers.template.test.ts

@@ -0,0 +1,151 @@
+/**
+ * Tests for userHandling.newUserTemplate: NewUserBase.createNewUser builds the new user as a copy of a
+ * template user through the record-cloning engine, and falls back to a plain user whenever the template
+ * can't be used (missing, not flagged IsTemplate, or the copy fails), so sign-in never breaks.
+ */
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+
+const {
+    mockConfig,
+    mockClone,
+    mockRunView,
+    mockLogError,
+    mockProvider,
+    savedUsers,
+} = vi.hoisted(() => {
+    const savedUsers: Array<Record<string, unknown>> = [];
+    const makeUser = () => {
+        const user: Record<string, unknown> & { NewRecord: () => void; Load: (id: string) => Promise<boolean>; Save: () => Promise<boolean> } = {
+            NewRecord: vi.fn(() => {
+                user.ID = 'plain-user-id';
+                user.Created = 'plain';
+            }),
+            Load: vi.fn(async (id: string) => {
+                user.ID = id;
+                user.Created = 'template';
+                return true;
+            }),
+            Save: vi.fn(async () => {
+                savedUsers.push({ ...user });
+                return true;
+            }),
+            LatestResult: null,
+        };
+        return user;
+    };
+    return {
+        mockConfig: {
+            userHandling: {
+                newUserRoles: [] as string[],
+                CreateUserApplicationRecords: false,
+                UserApplications: [] as string[],
+                contextUserForNewUserCreation: '',
+                newUserTemplate: { email: 'demo@example.org', preset: 'template' } as { email: string; preset: string } | undefined,
+            },
+        },
+        mockClone: vi.fn(),
+        mockRunView: vi.fn(),
+        mockLogError: vi.fn(),
+        mockProvider: {
+            GetEntityObject: vi.fn(async () => makeUser()),
+            BeginTransaction: vi.fn(),
+            CommitTransaction: vi.fn(),
+            RollbackTransaction: vi.fn(),
+            Roles: [],
+            Applications: [],
+        },
+        savedUsers,
+    };
+});
+
+vi.mock('../config.js', () => ({ configInfo: mockConfig }));
+vi.mock('../isolatedProvider.js', () => ({ CreateIsolatedProvider: vi.fn(async () => mockProvider) }));
+vi.mock('../auth/principals.js', () => ({ ResolveConfiguredPrincipal: vi.fn(() => ({ ID: 'system-id', Type: 'Owner' })) }));
+vi.mock('@memberjunction/record-cloning', () => ({
+    RecordCloneEngine: class {
+        Clone = mockClone;
+    },
+}));
+vi.mock('@memberjunction/core', async (importOriginal) => {
+    const actual = await importOriginal<typeof import('@memberjunction/core')>();
+    return {
+        ...actual,
+        RunView: { FromMetadataProvider: () => ({ RunView: mockRunView }) },
+        LogError: mockLogError,
+        LogStatus: vi.fn(),
+    };
+});
+vi.mock('@memberjunction/core-entities', () => ({ UserInfoEngine: { GetDefaultApplicationsForNewUser: () => [] } }));
+
+import { NewUserBase } from '../auth/newUsers.js';
+
+const templateRow = (isTemplate: boolean) => ({ Success: true, Results: [{ ID: 'tpl-id', IsTemplate: isTemplate }] });
+const cloned = { Success: true, ResultCode: 'SUCCESS', Warnings: [], RecordsCloned: 120, Roots: [{ EntityName: 'MJ: Users', SourceKey: { KeyValuePairs: [] }, TargetKey: { KeyValuePairs: [{ FieldName: 'ID', Value: 'new-user-id' }] } }] };
+
+describe('NewUserBase.createNewUser with newUserTemplate', () => {
+    beforeEach(() => {
+        vi.clearAllMocks();
+        savedUsers.length = 0;
+        mockConfig.userHandling.newUserTemplate = { email: 'demo@example.org', preset: 'template' };
+    });
+
+    it('creates the user as an active copy of the template', async () => {
+        mockRunView.mockResolvedValue(templateRow(true));
+        mockClone.mockResolvedValue(cloned);
+
+        const user = await new NewUserBase().createNewUser('Jane', 'Doe', 'jane@example.com');
+
+        expect(mockClone).toHaveBeenCalledWith(
+            expect.objectContaining({
+                EntityName: 'MJ: Users',
+                SourceRecordKey: expect.objectContaining({ KeyValuePairs: [expect.objectContaining({ FieldName: 'ID', Value: 'tpl-id' })] }),
+                Preset: 'template',
+                PromptedValues: { Email: 'jane@example.com', FirstName: 'Jane', LastName: 'Doe' },
+            }),
+            expect.objectContaining({ ID: 'system-id' })
+        );
+        expect(user?.ID).toBe('new-user-id');
+        expect(savedUsers).toEqual([expect.objectContaining({ ID: 'new-user-id', Created: 'template', IsActive: true, LinkedRecordType: 'None' })]);
+        expect(mockProvider.BeginTransaction).not.toHaveBeenCalled();
+    });
+
+    it('falls back to a plain user when the template user is not flagged IsTemplate', async () => {
+        mockRunView.mockResolvedValue(templateRow(false));
+
+        const user = await new NewUserBase().createNewUser('Jane', 'Doe', 'jane@example.com');
+
+        expect(mockClone).not.toHaveBeenCalled();
+        expect(mockLogError.mock.calls.flat().join(' ')).toContain('not marked as a template user');
+        expect(user?.ID).toBe('plain-user-id');
+        expect(savedUsers[0]).toEqual(expect.objectContaining({ Created: 'plain', Email: 'jane@example.com', IsActive: true }));
+    });
+
+    it('falls back to a plain user when no user has the template email', async () => {
+        mockRunView.mockResolvedValue({ Success: true, Results: [] });
+
+        const user = await new NewUserBase().createNewUser('Jane', 'Doe', 'jane@example.com');
+
+        expect(mockClone).not.toHaveBeenCalled();
+        expect(user?.ID).toBe('plain-user-id');
+    });
+
+    it('falls back to a plain user when the copy is blocked', async () => {
+        mockRunView.mockResolvedValue(templateRow(true));
+        mockClone.mockResolvedValue({ Success: false, ResultCode: 'BLOCKED', Warnings: [{ Severity: 'Error', Code: 'FORBIDDEN', Message: 'needs Clone Records' }] });
+
+        const user = await new NewUserBase().createNewUser('Jane', 'Doe', 'jane@example.com');
+
+        expect(mockLogError.mock.calls.flat().join(' ')).toContain('needs Clone Records');
+        expect(user?.ID).toBe('plain-user-id');
+    });
+
+    it('creates a plain user, as before, when no template is configured', async () => {
+        mockConfig.userHandling.newUserTemplate = undefined;
+
+        const user = await new NewUserBase().createNewUser('Jane', 'Doe', 'jane@example.com');
+
+        expect(mockRunView).not.toHaveBeenCalled();
+        expect(mockClone).not.toHaveBeenCalled();
+        expect(user?.ID).toBe('plain-user-id');
+    });
+});

package/src/__tests__/newUsers.test.ts

@@ -30,6 +30,8 @@ const {
     mockBeginTransaction,
     mockCommitTransaction,
     mockRollbackTransaction,
+    mockGlobalProviderCalls,
+    mockCreateIsolatedProvider,
     mockGetDefaultApplicationsForNewUser,
     mockRolesArray,
     mockApplicationsArray,
@@ -69,6 +71,10 @@ const {
         mockBeginTransaction: vi.fn(),
         mockCommitTransaction: vi.fn(),
         mockRollbackTransaction: vi.fn(),
+        // Every call new-user creation makes on the SHARED Metadata.Provider. Must stay empty: a
+        // transaction there nests into every concurrent request's (see CreateIsolatedProvider).
+        mockGlobalProviderCalls: [] as string[],
+        mockCreateIsolatedProvider: vi.fn(),
         mockGetDefaultApplicationsForNewUser: vi.fn(),
         mockRolesArray: [] as Array<{ ID: string; Name: string }>,
         mockApplicationsArray: [] as Array<{ ID: string; Name: string }>,
@@ -79,6 +85,9 @@ const {
 
 vi.mock('../config.js', () => ({ configInfo: mockConfig }));
 
+// The provider new-user creation must use: its own instance, so its transaction is its own.
+vi.mock('../isolatedProvider.js', () => ({ CreateIsolatedProvider: mockCreateIsolatedProvider }));
+
 vi.mock('@memberjunction/generic-database-provider', () => {
     const instance = {
         get Users() {
@@ -89,6 +98,18 @@ vi.mock('@memberjunction/generic-database-provider', () => {
         },
         Refresh: mockRefresh,
         GetSystemUser: vi.fn(),
+        /**
+         * The real cache falls back to a database read on a miss. The stub answers from
+         * the same array `Users` exposes, so these tests still describe the cache's behaviour.
+         */
+        FindUser: vi.fn(async ({ Email }: { Email?: string }) =>
+            mockCacheUsers.find((u: UserInfo) => {
+                if (!u.Email || u.Email.trim() === '') {
+                    console.error(`SYSTEM METADATA ISSUE: User ${u.ID} has no email address`);
+                    return false;
+                }
+                return u.Email.toLowerCase().trim() === (Email ?? '').toLowerCase().trim();
+            })),
     };
     return {
         UserCache: class MockUserCache {
@@ -104,10 +125,11 @@ vi.mock('@memberjunction/generic-database-provider', () => {
 
 vi.mock('@memberjunction/core', async (importOriginal) => {
     const actual = await importOriginal<typeof import('@memberjunction/core')>();
-    const provider = {
-        BeginTransaction: mockBeginTransaction,
-        CommitTransaction: mockCommitTransaction,
-        RollbackTransaction: mockRollbackTransaction,
+    // The shared global provider: records any use instead of doing anything.
+    const globalProvider = {
+        BeginTransaction: async () => { mockGlobalProviderCalls.push('BeginTransaction'); },
+        CommitTransaction: async () => { mockGlobalProviderCalls.push('CommitTransaction'); },
+        RollbackTransaction: async () => { mockGlobalProviderCalls.push('RollbackTransaction'); },
         Dialect: { BooleanLiteral: (value: boolean) => (value ? '1' : '0') },
     };
     class MockMetadata {
@@ -118,9 +140,10 @@ vi.mock('@memberjunction/core', async (importOriginal) => {
             return mockApplicationsArray;
         }
         public GetEntityObject(entityName: string, contextUser?: UserInfo): Promise<unknown> {
+            mockGlobalProviderCalls.push(`GetEntityObject:${entityName}`);
             return mockGetEntityObject(entityName, contextUser);
         }
-        static Provider = provider;
+        static Provider = globalProvider;
     }
     class MockUserInfo {
         constructor(_provider: unknown, initData: Record<string, unknown>) {
@@ -128,6 +151,9 @@ vi.mock('@memberjunction/core', async (importOriginal) => {
         }
     }
     class MockRunView {
+        public static FromMetadataProvider(_provider: unknown): MockRunView {
+            return new MockRunView();
+        }
         public RunView(params: unknown, contextUser?: UserInfo): Promise<unknown> {
             return mockRunViewFn(params, contextUser);
         }
@@ -295,6 +321,21 @@ beforeEach(() => {
     });
     mockRunViewFn.mockResolvedValue({ Success: true, Results: [] });
     mockGetDefaultApplicationsForNewUser.mockReturnValue([]);
+
+    mockGlobalProviderCalls.length = 0;
+    mockCreateIsolatedProvider.mockImplementation(async () => ({
+        BeginTransaction: mockBeginTransaction,
+        CommitTransaction: mockCommitTransaction,
+        RollbackTransaction: mockRollbackTransaction,
+        Dialect: { BooleanLiteral: (value: boolean) => (value ? '1' : '0') },
+        get Roles() {
+            return mockRolesArray;
+        },
+        get Applications() {
+            return mockApplicationsArray;
+        },
+        GetEntityObject: (entityName: string, contextUser?: UserInfo) => mockGetEntityObject(entityName, contextUser),
+    }));
 });
 
 // ─── NewUserBase.createNewUser ──────────────────────────────────────────────
@@ -303,6 +344,34 @@ describe('NewUserBase.createNewUser', () => {
     const create = (first = 'Ada', last = 'Lovelace', email = 'ada@example.com') =>
         new NewUserBase().createNewUser(first, last, email);
 
+    describe('provider isolation', () => {
+        it('runs the whole provisioning on its own provider, never the shared Metadata.Provider', async () => {
+            mockConfig.userHandling.CreateUserApplicationRecords = true;
+            mockConfig.userHandling.UserApplications = ['CRM'];
+            mockRunViewFn.mockResolvedValue({ Success: true, Results: [{ EntityID: 'ent-1', Entity: 'Accounts' }] });
+
+            const user = await create();
+
+            expect(user).toBeTruthy();
+            expect(mockCreateIsolatedProvider).toHaveBeenCalledTimes(1);
+            expect(mockBeginTransaction).toHaveBeenCalledTimes(1);
+            expect(mockCommitTransaction).toHaveBeenCalledTimes(1);
+            // User, role, application and application-entity records all came from the isolated one.
+            expect(getEntityObjectCalls.map((c) => c.entityName)).toEqual([
+                'MJ: Users', 'MJ: User Roles', 'MJ: User Applications', 'MJ: User Application Entities',
+            ]);
+            expect(mockGlobalProviderCalls).toEqual([]);
+        });
+
+        it('rolls back on the isolated provider too, never the shared one', async () => {
+            saveBehavior['MJ: Users'] = () => false;
+
+            expect(await create()).toBeNull();
+            expect(mockRollbackTransaction).toHaveBeenCalledTimes(1);
+            expect(mockGlobalProviderCalls).toEqual([]);
+        });
+    });
+
     describe('context-user resolution', () => {
         it('uses the configured contextUserForNewUserCreation for every entity it creates', async () => {
             const user = await create();

package/src/__tests__/orphanedConversationDetailReconciler.test.ts

@@ -20,8 +20,10 @@ const { mockGetEntityObject, writableStore } = vi.hoisted(() => ({
     writableStore: { last: null as Record<string, unknown> | null },
 }));
 
-vi.mock('@memberjunction/global', () => ({
-    UUIDsEqual: (a: string, b: string) => String(a).toLowerCase() === String(b).toLowerCase(),
+// The real UUID helpers: the reconciler indexes users with IndexByUUID, so a stub that only
+// provides UUIDsEqual would make the owner lookup throw (and the pass silently do nothing).
+vi.mock('@memberjunction/global', async (importOriginal) => ({
+    ...(await importOriginal<typeof import('@memberjunction/global')>()),
 }));
 
 vi.mock('@memberjunction/sqlserver-dataprovider', () => ({
@@ -230,6 +232,19 @@ describe('ReconcileOrphanedConversationDetails', () => {
         );
     });
 
+    it('resolves the owner when the conversation spells the user ID in a different case', async () => {
+        // The cached user is 'OWNER-1'; SQL Server and PostgreSQL disagree on UUID case, so the
+        // conversation row may carry it lower-cased. The owner lookup must still find the user.
+        script([detail()], [{ ConversationDetailID: DETAIL_ID, Status: 'Failed', CompletedAt: longAgo() }], 'owner-1');
+
+        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);
 

package/src/__tests__/postgresqlPoolSettings.test.ts

@@ -0,0 +1,131 @@
+/**
+ * PostgreSQL pools read the same databaseSettings values as SQL Server, with the same defaults.
+ */
+import { describe, it, expect } from 'vitest';
+import {
+    BuildPostgreSQLConnectionConfig,
+    CODEGEN_STATEMENT_TIMEOUT_MS,
+    ResolvePostgreSQLEndpoint,
+    ResolvePostgreSQLReadOnlyCredentials,
+    ToPGPoolConfig
+} from '../postgresqlPoolSettings.js';
+import type { DatabaseSettingsInfo } from '../config.js';
+import { DescribeReadOnlyLoginOverreach } from '../postgresqlPoolSettings.js';
+import type { ReadOnlyLoginCheckClient, ReadOnlyLoginGrants } from '../postgresqlPoolSettings.js';
+
+const defaults: DatabaseSettingsInfo = {
+    connectionTimeout: 45000,
+    requestTimeout: 30000,
+    metadataCacheRefreshInterval: 180000,
+    connectionPool: { max: 50, min: 5, idleTimeoutMillis: 30000, acquireTimeoutMillis: 30000 }
+};
+const endpoint = { Host: 'db', Port: 5432, Database: 'mj', User: 'api', Password: 'secret' };
+
+describe('BuildPostgreSQLConnectionConfig', () => {
+    it('gives API pools requestTimeout as the statement timeout and the pool settings SQL Server uses', () => {
+        const config = BuildPostgreSQLConnectionConfig(endpoint, defaults, 'api');
+        expect(config).toMatchObject({
+            ...endpoint,
+            MaxConnections: 50,
+            MinConnections: 5,
+            IdleTimeoutMillis: 30000,
+            ConnectionTimeoutMillis: 30000,
+            StatementTimeoutMs: 30000,
+            IdleInTransactionSessionTimeoutMs: 60000
+        });
+    });
+
+    it('follows a configured requestTimeout and pool', () => {
+        const config = BuildPostgreSQLConnectionConfig(endpoint, {
+            ...defaults,
+            requestTimeout: 5000,
+            connectionPool: { max: 12, min: 1, idleTimeoutMillis: 7000, acquireTimeoutMillis: 9000 }
+        }, 'api');
+        expect(config).toMatchObject({ MaxConnections: 12, MinConnections: 1, IdleTimeoutMillis: 7000, ConnectionTimeoutMillis: 9000, StatementTimeoutMs: 5000, IdleInTransactionSessionTimeoutMs: 10000 });
+    });
+
+    it('sets no timeouts when requestTimeout is 0', () => {
+        const config = BuildPostgreSQLConnectionConfig(endpoint, { ...defaults, requestTimeout: 0 }, 'api');
+        expect(config.StatementTimeoutMs).toBe(0);
+        expect(config.IdleInTransactionSessionTimeoutMs).toBe(0);
+    });
+
+    it('keeps the read-only pool small but gives it the API timeouts', () => {
+        const config = BuildPostgreSQLConnectionConfig(endpoint, defaults, 'read-only');
+        expect(config).toMatchObject({ MaxConnections: 10, MinConnections: 0, StatementTimeoutMs: 30000, IdleInTransactionSessionTimeoutMs: 60000 });
+        expect(BuildPostgreSQLConnectionConfig(endpoint, { ...defaults, connectionPool: { max: 4, min: 1, idleTimeoutMillis: 1, acquireTimeoutMillis: 1 } }, 'read-only').MaxConnections).toBe(4);
+    });
+
+    it('gives the CodeGen pool the long timeout the SQL Server CodeGen pool has, and no idle-in-transaction limit', () => {
+        const config = BuildPostgreSQLConnectionConfig(endpoint, defaults, 'codegen');
+        expect(config.StatementTimeoutMs).toBe(CODEGEN_STATEMENT_TIMEOUT_MS);
+        expect(CODEGEN_STATEMENT_TIMEOUT_MS).toBe(600000);
+        expect(config.IdleInTransactionSessionTimeoutMs).toBe(0);
+        expect(config.MaxConnections).toBe(10);
+    });
+});
+
+describe('ToPGPoolConfig', () => {
+    it('maps the connection config onto pg.Pool option names', () => {
+        const pool = ToPGPoolConfig(BuildPostgreSQLConnectionConfig(endpoint, defaults, 'api'));
+        expect(pool).toEqual({
+            host: 'db', port: 5432, database: 'mj', user: 'api', password: 'secret',
+            max: 50, min: 5, idleTimeoutMillis: 30000, connectionTimeoutMillis: 30000,
+            statement_timeout: 30000, idle_in_transaction_session_timeout: 60000
+        });
+    });
+
+    it('leaves the timeouts out when they are 0', () => {
+        const pool = ToPGPoolConfig(BuildPostgreSQLConnectionConfig(endpoint, { ...defaults, requestTimeout: 0 }, 'api'));
+        expect(pool).not.toHaveProperty('statement_timeout');
+        expect(pool).not.toHaveProperty('idle_in_transaction_session_timeout');
+    });
+});
+
+describe('ResolvePostgreSQLEndpoint', () => {
+    it('prefers PG_* variables over DB_* ones', () => {
+        expect(ResolvePostgreSQLEndpoint({ PG_HOST: 'pg', DB_HOST: 'db', DB_PORT: '6000', DB_DATABASE: 'd', DB_USERNAME: 'u', DB_PASSWORD: 'p' }))
+            .toEqual({ Host: 'pg', Port: 6000, Database: 'd', User: 'u', Password: 'p' });
+    });
+
+    it('falls back to localhost:5432 and the postgres user', () => {
+        expect(ResolvePostgreSQLEndpoint({})).toEqual({ Host: 'localhost', Port: 5432, Database: '', User: 'postgres', Password: '' });
+    });
+});
+
+describe('ResolvePostgreSQLReadOnlyCredentials', () => {
+    it('uses the dbReadOnlyUsername / dbReadOnlyPassword settings SQL Server uses', () => {
+        expect(ResolvePostgreSQLReadOnlyCredentials({ dbReadOnlyUsername: 'ro', dbReadOnlyPassword: 'pw' }, {}))
+            .toEqual({ User: 'ro', Password: 'pw' });
+    });
+
+    it('falls back to PG_READ_ONLY_* when the settings are absent', () => {
+        expect(ResolvePostgreSQLReadOnlyCredentials({}, { PG_READ_ONLY_USERNAME: 'pgro', PG_READ_ONLY_PASSWORD: 'x' }))
+            .toEqual({ User: 'pgro', Password: 'x' });
+    });
+
+    it('returns null when no complete pair is configured', () => {
+        expect(ResolvePostgreSQLReadOnlyCredentials({ dbReadOnlyUsername: 'ro' }, { PG_READ_ONLY_USERNAME: 'pgro' })).toBeNull();
+    });
+});
+
+describe('DescribeReadOnlyLoginOverreach', () => {
+    const clientAnswering = (row: ReadOnlyLoginGrants): ReadOnlyLoginCheckClient => ({
+        query: async () => ({ rows: [row] }),
+    });
+
+    it('says nothing for a login that reads only views', async () => {
+        expect(await DescribeReadOnlyLoginOverreach(clientAnswering({ ReadsServerFiles: false, ReadableBaseTables: 0 }), '__mj')).toEqual([]);
+    });
+
+    it('warns when the login can read base tables', async () => {
+        const warnings = await DescribeReadOnlyLoginOverreach(clientAnswering({ ReadsServerFiles: false, ReadableBaseTables: 412 }), '__mj');
+        expect(warnings).toHaveLength(1);
+        expect(warnings[0]).toMatch(/can read 412 base table\(s\) in schema "__mj"/);
+    });
+
+    it('warns when the login can read server files', async () => {
+        const warnings = await DescribeReadOnlyLoginOverreach(clientAnswering({ ReadsServerFiles: true, ReadableBaseTables: 0 }), '__mj');
+        expect(warnings[0]).toMatch(/pg_read_server_files/);
+    });
+});

package/src/__tests__/realtimeSessions/RealtimeSessionEventService.test.ts

@@ -0,0 +1,201 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import type { IMetadataProvider, UserInfo } from '@memberjunction/core';
+import { MJGlobal } from '@memberjunction/global';
+import type { PubSubEngine } from 'type-graphql';
+import { PubSubManager } from '../../generic/PubSubManager.js';
+import {
+    ParseReplicatedRealtimeSessionEvent,
+    REALTIME_SESSION_EVENTS_TOPIC,
+    RealtimeSessionEventService,
+    type RealtimeSessionEventTopicPayload,
+} from '../../realtimeSessions/RealtimeSessionEventService.js';
+
+const OWNER = 'AAAAAAAA-0000-4000-8000-000000000001';
+const SESSION_ID = 'BBBBBBBB-0000-4000-8000-000000000001';
+const CONVERSATION_ID = 'CCCCCCCC-0000-4000-8000-000000000001';
+const USER = { ID: OWNER } as UserInfo;
+
+const VERIFIED = { VerifiedEmail: 'pat@example.com', VerifiedName: 'Pat', VerifiedAt: '2026-10-02T12:00:00.000Z', Method: 'link' as const };
+
+/** A provider that serves one session (+ conversation) — or nothing. */
+function provider(found = true, externalId: string | null = 'scope-1'): IMetadataProvider {
+    return {
+        GetEntityObject: vi.fn(async (name: string) => {
+            if (name === 'MJ: AI Agent Sessions') {
+                return found
+                    ? { ID: SESSION_ID, UserID: OWNER, ConversationID: CONVERSATION_ID, Load: vi.fn(async () => true) }
+                    : { Load: vi.fn(async () => false) };
+            }
+            return { ExternalID: externalId, Load: vi.fn(async () => true) };
+        }),
+    } as unknown as IMetadataProvider;
+}
+
+describe('RealtimeSessionEventService', () => {
+    const published: Array<{ topic: string; payload: RealtimeSessionEventTopicPayload }> = [];
+
+    beforeEach(() => {
+        published.length = 0;
+        const engine = { publish: vi.fn(async (topic: string, payload: RealtimeSessionEventTopicPayload) => void published.push({ topic, payload })) };
+        PubSubManager.Instance.SetPubSubEngine(engine as unknown as PubSubEngine);
+        RealtimeSessionEventService.Instance.SetReplicationHook(undefined);
+    });
+
+    describe('Publish', () => {
+        it('publishes on the shared topic with the session routing snapshot', async () => {
+            const result = await RealtimeSessionEventService.Instance.Publish({
+                AgentSessionID: SESSION_ID,
+                Type: 'identity.verified',
+                Payload: VERIFIED,
+                ContextUser: USER,
+                Provider: provider(),
+            });
+            expect(result).toEqual({ Success: true });
+            expect(published).toHaveLength(1);
+            expect(published[0].topic).toBe(REALTIME_SESSION_EVENTS_TOPIC);
+            expect(published[0].payload).toMatchObject({
+                Type: 'identity.verified',
+                AgentSessionID: SESSION_ID,
+                OwnerUserID: OWNER,
+                ScopeKey: 'scope-1',
+                SourceServerId: MJGlobal.Instance.ProcessUUID,
+            });
+            expect(JSON.parse(published[0].payload.PayloadJson)).toEqual(VERIFIED);
+            expect(Date.parse(published[0].payload.OccurredAt)).not.toBeNaN();
+        });
+
+        it('snapshots a null scope for a session whose conversation carries none', async () => {
+            await RealtimeSessionEventService.Instance.Publish({
+                AgentSessionID: SESSION_ID,
+                Type: 'identity.verified',
+                Payload: VERIFIED,
+                ContextUser: USER,
+                Provider: provider(true, null),
+            });
+            expect(published[0].payload.ScopeKey).toBeNull();
+        });
+
+        it('fails (and publishes nothing) when the session cannot be found', async () => {
+            const result = await RealtimeSessionEventService.Instance.Publish({
+                AgentSessionID: SESSION_ID,
+                Type: 'identity.verified',
+                Payload: VERIFIED,
+                ContextUser: USER,
+                Provider: provider(false),
+            });
+            expect(result.Success).toBe(false);
+            expect(result.ErrorMessage).toContain('not found');
+            expect(published).toHaveLength(0);
+        });
+
+        it('returns a failure instead of throwing when reading the session throws', async () => {
+            const broken = { GetEntityObject: vi.fn(async () => { throw new Error('db down'); }) } as unknown as IMetadataProvider;
+            const result = await RealtimeSessionEventService.Instance.Publish({
+                AgentSessionID: SESSION_ID,
+                Type: 'identity.verified',
+                Payload: VERIFIED,
+                ContextUser: USER,
+                Provider: broken,
+            });
+            expect(result).toMatchObject({ Success: false });
+            expect(result.ErrorMessage).toContain('db down');
+        });
+    });
+
+    describe('PublishRouted', () => {
+        it('fails loudly when PubSub is not configured', () => {
+            PubSubManager.Instance.SetPubSubEngine(null as unknown as PubSubEngine);
+            const result = RealtimeSessionEventService.Instance.PublishRouted({ AgentSessionID: SESSION_ID, OwnerUserID: OWNER, ScopeKey: null }, 'identity.verified', VERIFIED);
+            expect(result).toMatchObject({ Success: false });
+            expect(result.ErrorMessage).toContain('PubSub is not configured');
+        });
+
+        it('hands every locally published event to the replication hook', () => {
+            const hook = vi.fn();
+            RealtimeSessionEventService.Instance.SetReplicationHook(hook);
+            RealtimeSessionEventService.Instance.PublishRouted({ AgentSessionID: SESSION_ID, OwnerUserID: OWNER, ScopeKey: null }, 'identity.verified', VERIFIED);
+            expect(hook).toHaveBeenCalledTimes(1);
+            expect(hook.mock.calls[0][0]).toMatchObject({ AgentSessionID: SESSION_ID, OwnerUserID: OWNER, Type: 'identity.verified' });
+        });
+
+        it('never lets a failing replication hook break local delivery', () => {
+            RealtimeSessionEventService.Instance.SetReplicationHook(() => {
+                throw new Error('redis down');
+            });
+            const result = RealtimeSessionEventService.Instance.PublishRouted({ AgentSessionID: SESSION_ID, OwnerUserID: OWNER, ScopeKey: null }, 'identity.verified', VERIFIED);
+            expect(result).toEqual({ Success: true });
+            expect(published).toHaveLength(1);
+        });
+    });
+
+    describe('PublishReplicated', () => {
+        it('republishes locally and never back through the replication hook (no loop)', () => {
+            const hook = vi.fn();
+            RealtimeSessionEventService.Instance.SetReplicationHook(hook);
+            const payload: RealtimeSessionEventTopicPayload = {
+                Type: 'identity.verified',
+                AgentSessionID: SESSION_ID,
+                OccurredAt: '2026-10-02T12:00:00.000Z',
+                PayloadJson: JSON.stringify(VERIFIED),
+                OwnerUserID: OWNER,
+                ScopeKey: null,
+                SourceServerId: 'other-instance',
+            };
+            RealtimeSessionEventService.Instance.PublishReplicated(payload);
+            expect(published).toEqual([{ topic: REALTIME_SESSION_EVENTS_TOPIC, payload }]);
+            expect(hook).not.toHaveBeenCalled();
+        });
+    });
+});
+
+describe('ParseReplicatedRealtimeSessionEvent', () => {
+    const wire = (over: Record<string, unknown> = {}) =>
+        JSON.stringify({
+            Type: 'identity.verified',
+            AgentSessionID: SESSION_ID,
+            OccurredAt: '2026-10-02T12:00:00.000Z',
+            PayloadJson: '{}',
+            OwnerUserID: OWNER,
+            ScopeKey: 'scope-1',
+            SourceServerId: 'other-instance',
+            ...over,
+        });
+
+    it('accepts a well-formed event from another instance', () => {
+        expect(ParseReplicatedRealtimeSessionEvent(wire(), 'this-instance')).toEqual({
+            Type: 'identity.verified',
+            AgentSessionID: SESSION_ID,
+            OccurredAt: '2026-10-02T12:00:00.000Z',
+            PayloadJson: '{}',
+            OwnerUserID: OWNER,
+            ScopeKey: 'scope-1',
+            SourceServerId: 'other-instance',
+        });
+    });
+
+    it('drops our own echo', () => {
+        expect(ParseReplicatedRealtimeSessionEvent(wire({ SourceServerId: 'this-instance' }), 'this-instance')).toBeNull();
+    });
+
+    it('fails closed when the routing identity is missing or malformed', () => {
+        expect(ParseReplicatedRealtimeSessionEvent(wire({ OwnerUserID: undefined }), 'x')).toBeNull();
+        expect(ParseReplicatedRealtimeSessionEvent(wire({ OwnerUserID: '' }), 'x')).toBeNull();
+        expect(ParseReplicatedRealtimeSessionEvent(wire({ OwnerUserID: 5 }), 'x')).toBeNull();
+        expect(ParseReplicatedRealtimeSessionEvent(wire({ ScopeKey: 5 }), 'x')).toBeNull();
+    });
+
+    it('normalises an absent scope to null and tolerates an absent source', () => {
+        const parsed = ParseReplicatedRealtimeSessionEvent(wire({ ScopeKey: undefined, SourceServerId: undefined }), 'x');
+        expect(parsed?.ScopeKey).toBeNull();
+        expect(parsed?.SourceServerId).toBeUndefined();
+    });
+
+    it('drops non-JSON, non-objects and events missing required strings', () => {
+        expect(ParseReplicatedRealtimeSessionEvent('{nope', 'x')).toBeNull();
+        expect(ParseReplicatedRealtimeSessionEvent('"text"', 'x')).toBeNull();
+        expect(ParseReplicatedRealtimeSessionEvent('null', 'x')).toBeNull();
+        expect(ParseReplicatedRealtimeSessionEvent(wire({ Type: undefined }), 'x')).toBeNull();
+        expect(ParseReplicatedRealtimeSessionEvent(wire({ PayloadJson: undefined }), 'x')).toBeNull();
+        expect(ParseReplicatedRealtimeSessionEvent(wire({ SourceServerId: 7 }), 'x')).toBeNull();
+    });
+});