@memberjunction/server 6.2.0-edge.5 → 6.2.0-edge.7

package/src/__tests__/apiRootBoot.test.ts

@@ -90,7 +90,7 @@ function bootCoreRoutes(): { app: Application; paths: string[] } {
 }
 
 async function statusOf(app: Application, path: string): Promise<number> {
-    const server = app.listen(0);
+    const server = app.listen(0, '127.0.0.1');
     try {
         await new Promise<void>((resolve) => server.once('listening', () => resolve()));
         const { port } = server.address() as AddressInfo;

package/src/__tests__/backgroundSweepConfigUnits.test.ts

@@ -0,0 +1,153 @@
+/**
+ * Config contract for the two background sweeps an idle MJAPI runs against its database: the AI
+ * Agent Session janitor (`agentSessions.janitor`) and the agent-run watchdog (`agentRunWatchdog`).
+ *
+ * Pins three things: the shipped defaults are exactly the values MJAPI always ran with (so existing
+ * deployments see no change), each sweep can be turned off the documented way, and the env-var
+ * readers that feed `DEFAULT_SERVER_CONFIG` reject typos instead of silently running a default or
+ * a zero-delay timer.
+ */
+import { describe, it, expect } from 'vitest';
+import {
+    AgentRunWatchdogDefaultsFromEnv,
+    AgentRunWatchdogSchema,
+    AgentSessionsDefaultsFromEnv,
+    AgentSessionsSchema,
+    ConversationDetailReconcilerDefaultsFromEnv,
+    ConversationDetailReconcilerSchema,
+    EnabledFromEnv,
+    IntervalMsFromEnv,
+} from '../backgroundSweepConfigUnits.js';
+
+describe('agentSessions.janitor schema', () => {
+    it('defaults to what MJAPI has always run: janitor on every 60s (15-minute idle close), bridge reconcile on every 10 min', () => {
+        expect(AgentSessionsSchema.parse({})).toEqual({
+            janitor: { enabled: true, sweepIntervalMs: 60_000, closeThresholdMinutes: 15 },
+            bridgeReconciler: { enabled: true, sweepIntervalMs: 600_000 },
+            handoffOfferExpiry: { enabled: true, sweepIntervalMs: 15_000 },
+        });
+    });
+
+    it('accepts enabled: false and a longer interval', () => {
+        const parsed = AgentSessionsSchema.parse({ janitor: { enabled: false, sweepIntervalMs: 3_600_000 }, bridgeReconciler: { enabled: false } });
+        expect(parsed.janitor).toEqual({ enabled: false, sweepIntervalMs: 3_600_000, closeThresholdMinutes: 15 });
+        expect(parsed.bridgeReconciler).toEqual({ enabled: false, sweepIntervalMs: 600_000 });
+    });
+
+    it('rejects a zero or negative interval (turn the tick off with enabled: false instead)', () => {
+        expect(AgentSessionsSchema.safeParse({ janitor: { sweepIntervalMs: 0 } }).success).toBe(false);
+        expect(AgentSessionsSchema.safeParse({ janitor: { closeThresholdMinutes: -1 } }).success).toBe(false);
+        expect(AgentSessionsSchema.safeParse({ bridgeReconciler: { sweepIntervalMs: 0 } }).success).toBe(false);
+    });
+});
+
+describe('conversationDetailReconciler schema', () => {
+    it('defaults to what MJAPI has always run: on, every 5 minutes', () => {
+        expect(ConversationDetailReconcilerSchema.parse({})).toEqual({ enabled: true, sweepIntervalMs: 300_000 });
+    });
+
+    it('accepts enabled: false and rejects a zero interval', () => {
+        expect(ConversationDetailReconcilerSchema.parse({ enabled: false }).enabled).toBe(false);
+        expect(ConversationDetailReconcilerSchema.safeParse({ sweepIntervalMs: 0 }).success).toBe(false);
+    });
+});
+
+describe('DEFAULT_SERVER_CONFIG blocks from the environment', () => {
+    it('an empty environment gives exactly the shipped defaults', () => {
+        expect(AgentSessionsDefaultsFromEnv({})).toEqual(AgentSessionsSchema.parse({}));
+        expect(ConversationDetailReconcilerDefaultsFromEnv({})).toEqual(ConversationDetailReconcilerSchema.parse({}));
+        expect(AgentRunWatchdogDefaultsFromEnv({})).toEqual(AgentRunWatchdogSchema.parse({}));
+    });
+
+    it('reads every documented variable', () => {
+        const env = {
+            MJ_SESSION_JANITOR_ENABLED: 'false',
+            MJ_SESSION_JANITOR_SWEEP_INTERVAL_MS: '120000',
+            MJ_BRIDGE_RECONCILER_ENABLED: 'off',
+            MJ_BRIDGE_RECONCILER_SWEEP_INTERVAL_MS: '1200000',
+            MJ_CONVERSATION_DETAIL_RECONCILER_ENABLED: '0',
+            MJ_CONVERSATION_DETAIL_RECONCILER_SWEEP_INTERVAL_MS: '900000',
+            MJ_HANDOFF_OFFER_EXPIRY_ENABLED: 'no',
+            MJ_HANDOFF_OFFER_EXPIRY_SWEEP_INTERVAL_MS: '60000',
+            MJ_AGENT_RUN_WATCHDOG_SWEEP_INTERVAL_MS: '0',
+        };
+        expect(AgentSessionsDefaultsFromEnv(env)).toEqual({
+            janitor: { enabled: false, sweepIntervalMs: 120_000, closeThresholdMinutes: 15 },
+            bridgeReconciler: { enabled: false, sweepIntervalMs: 1_200_000 },
+            handoffOfferExpiry: { enabled: false, sweepIntervalMs: 60_000 },
+        });
+        expect(ConversationDetailReconcilerDefaultsFromEnv(env)).toEqual({ enabled: false, sweepIntervalMs: 900_000 });
+        expect(AgentRunWatchdogDefaultsFromEnv(env).sweepIntervalMs).toBe(0);
+    });
+
+    it('a bad value fails, naming the variable', () => {
+        expect(() => AgentSessionsDefaultsFromEnv({ MJ_BRIDGE_RECONCILER_ENABLED: 'nope' }))
+            .toThrow('Invalid MJ_BRIDGE_RECONCILER_ENABLED "nope". Expected true or false.');
+        expect(() => ConversationDetailReconcilerDefaultsFromEnv({ MJ_CONVERSATION_DETAIL_RECONCILER_SWEEP_INTERVAL_MS: '0' }))
+            .toThrow(/Invalid MJ_CONVERSATION_DETAIL_RECONCILER_SWEEP_INTERVAL_MS "0"/);
+    });
+});
+
+describe('agentRunWatchdog schema', () => {
+    it('defaults to the watchdog MJAPI has always run: 5-min sweep, 30s heartbeat, 5-min stale threshold', () => {
+        expect(AgentRunWatchdogSchema.parse({})).toEqual({
+            sweepIntervalMs: 300_000,
+            heartbeatIntervalMs: 30_000,
+            staleThresholdMinutes: 5,
+        });
+    });
+
+    it('accepts sweepIntervalMs: 0 (startup sweep only)', () => {
+        expect(AgentRunWatchdogSchema.parse({ sweepIntervalMs: 0 }).sweepIntervalMs).toBe(0);
+    });
+
+    it('rejects a zero heartbeat (other instances would force-fail this one\'s runs) and negative values', () => {
+        expect(AgentRunWatchdogSchema.safeParse({ heartbeatIntervalMs: 0 }).success).toBe(false);
+        expect(AgentRunWatchdogSchema.safeParse({ staleThresholdMinutes: 0 }).success).toBe(false);
+        expect(AgentRunWatchdogSchema.safeParse({ sweepIntervalMs: -1 }).success).toBe(false);
+    });
+});
+
+describe('EnabledFromEnv', () => {
+    it('returns the fallback when the variable is unset or blank', () => {
+        expect(EnabledFromEnv('X', undefined, true)).toBe(true);
+        expect(EnabledFromEnv('X', null, false)).toBe(false);
+        expect(EnabledFromEnv('X', '  ', true)).toBe(true);
+    });
+
+    it.each(['false', 'FALSE', '0', 'no', 'off', 'n', 'f'])('%j turns the switch off', value => {
+        expect(EnabledFromEnv('X', value, true)).toBe(false);
+    });
+
+    it.each(['true', '1', 'yes', 'on', 'Y', 't'])('%j turns it on', value => {
+        expect(EnabledFromEnv('X', value, false)).toBe(true);
+    });
+
+    it('fails fast on anything else, naming the variable (a typo must not silently turn a sweep off)', () => {
+        expect(() => EnabledFromEnv('MJ_SESSION_JANITOR_ENABLED', 'flase', true))
+            .toThrow('Invalid MJ_SESSION_JANITOR_ENABLED "flase". Expected true or false.');
+    });
+});
+
+describe('IntervalMsFromEnv', () => {
+    it('returns the fallback when the variable is unset or blank', () => {
+        expect(IntervalMsFromEnv('X', undefined, 60_000, false)).toBe(60_000);
+        expect(IntervalMsFromEnv('X', '', 60_000, false)).toBe(60_000);
+    });
+
+    it('reads a number of milliseconds', () => {
+        expect(IntervalMsFromEnv('X', ' 3600000 ', 60_000, false)).toBe(3_600_000);
+    });
+
+    it('accepts 0 only where 0 means off', () => {
+        expect(IntervalMsFromEnv('MJ_AGENT_RUN_WATCHDOG_SWEEP_INTERVAL_MS', '0', 300_000, true)).toBe(0);
+        expect(() => IntervalMsFromEnv('MJ_SESSION_JANITOR_SWEEP_INTERVAL_MS', '0', 60_000, false))
+            .toThrow('Invalid MJ_SESSION_JANITOR_SWEEP_INTERVAL_MS "0". Expected a number of milliseconds greater than 0.');
+    });
+
+    it('fails fast on a typo, naming the variable', () => {
+        expect(() => IntervalMsFromEnv('MJ_AGENT_RUN_WATCHDOG_SWEEP_INTERVAL_MS', '5m', 300_000, true))
+            .toThrow('Invalid MJ_AGENT_RUN_WATCHDOG_SWEEP_INTERVAL_MS "5m". Expected a number of milliseconds, 0 or greater.');
+        expect(() => IntervalMsFromEnv('X', '-5', 60_000, true)).toThrow(/Invalid X/);
+    });
+});

package/src/__tests__/buildMagicLinkSessionUser.test.ts

@@ -0,0 +1,96 @@
+import { describe, it, expect, vi } from 'vitest';
+import { UserInfo } from '@memberjunction/core';
+import type jwt from 'jsonwebtoken';
+
+vi.mock('../config.js', () => ({
+  userEmailMap: {},
+  apiKey: 'test-api-key',
+  mj_core_schema: '__mj',
+  configInfo: {},
+}));
+vi.mock('../auth/index.js', () => ({
+  GetSigningKeys: vi.fn(),
+  GetSystemUser: vi.fn(),
+  GetValidationOptions: vi.fn(),
+  VerifyUserRecord: vi.fn(),
+  ExtractUserInfoFromPayload: vi.fn(),
+}));
+vi.mock('../util.js', () => ({
+  GetReadOnlyDataSource: vi.fn(),
+  GetReadWriteDataSource: vi.fn(),
+}));
+
+import { BuildMagicLinkSessionUser } from '../context.js';
+
+const uuid = (a: string, b: string) =>
+  [a.repeat(8), b.repeat(4), '4' + b.repeat(3), '8' + b.repeat(3), b.repeat(12)].join('-');
+const ANON_USER_ID = uuid('A', '0');
+const NAMED_USER_ID = uuid('B', '1');
+
+function makeUserRecord(id: string, email: string): UserInfo {
+  return new UserInfo(null, {
+    ID: id,
+    Name: 'Session Test User',
+    Email: email,
+    IsActive: true,
+    Type: 'User',
+    UserRoles: [],
+  });
+}
+
+describe('BuildMagicLinkSessionUser', () => {
+  it('sets AnonymousVisitorID from mj_sid for an anonymous magic-link token', () => {
+    const baseUser = makeUserRecord(ANON_USER_ID, 'anonymous@magic-link.local');
+    const payload: jwt.JwtPayload = {
+      mj_magic_link: true,
+      mj_anon: true,
+      mj_sid: 'sid-visitor-123',
+      mj_scopes: [{ inviteId: 'inv-1', appId: 'app-1', role: 'Widget Guest', resourceId: 'res-shared' }],
+    };
+
+    const result = BuildMagicLinkSessionUser(baseUser, payload);
+
+    expect(result).not.toBe(baseUser);
+    expect(result.IsMagicLinkAnonymous).toBe(true);
+    expect(result.AnonymousVisitorID).toBe('sid-visitor-123');
+    expect(result.MagicLinkScope?.ResourceID).toBe('res-shared');
+    expect(baseUser.AnonymousVisitorID).toBeUndefined();
+  });
+
+  it('rejects an anonymous magic-link token without mj_sid', () => {
+    const baseUser = makeUserRecord(ANON_USER_ID, 'anonymous@magic-link.local');
+    const missingSid: jwt.JwtPayload = {
+      mj_magic_link: true,
+      mj_anon: true,
+      mj_scopes: [{ inviteId: 'inv-1', appId: 'app-1', role: 'Widget Guest', resourceId: 'res-shared' }],
+    };
+    const blankSid: jwt.JwtPayload = {
+      mj_magic_link: true,
+      mj_anon: true,
+      mj_sid: '   ',
+    };
+
+    expect(() => BuildMagicLinkSessionUser(baseUser, missingSid)).toThrow(/mj_sid/);
+    expect(() => BuildMagicLinkSessionUser(baseUser, blankSid)).toThrow(/mj_sid/);
+  });
+
+  it('leaves AnonymousVisitorID undefined for a named magic-link token (with or without resource scope)', () => {
+    const baseUser = makeUserRecord(NAMED_USER_ID, 'named@example.com');
+    const unscopedNamed: jwt.JwtPayload = {
+      mj_magic_link: true,
+      mj_scopes: [{ inviteId: 'inv-named', appId: 'app-1', role: 'UI' }],
+    };
+    const scopedNamed: jwt.JwtPayload = {
+      mj_magic_link: true,
+      mj_scopes: [{ inviteId: 'inv-named-2', appId: 'app-1', role: 'UI', resourceId: 'res-named-1', resourceType: 'Report' }],
+    };
+
+    const unscopedResult = BuildMagicLinkSessionUser(baseUser, unscopedNamed);
+    expect(unscopedResult.AnonymousVisitorID).toBeUndefined();
+
+    const scopedResult = BuildMagicLinkSessionUser(baseUser, scopedNamed);
+    expect(scopedResult.IsMagicLinkAnonymous).toBe(false);
+    expect(scopedResult.MagicLinkScope?.ResourceID).toBe('res-named-1');
+    expect(scopedResult.AnonymousVisitorID).toBeUndefined();
+  });
+});

package/src/__tests__/cacheBroadcastProviders.test.ts

@@ -0,0 +1,403 @@
+import 'reflect-metadata';
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import type { EntityInfo, UserInfo } from '@memberjunction/core';
+import type { PubSubEngine } from 'type-graphql';
+import {
+    AzureWebPubSubBroadcastProvider,
+    AWSIoTCoreBroadcastProvider,
+    CacheInvalidationBroadcastManager,
+    GCPPubSubBroadcastProvider,
+    SequencedRoleBucketBroadcastProvider,
+    type AzureWebPubSubGroupMessage,
+    type AWSIoTCoreTopicMessage,
+    type GCPPubSubTopicMessage,
+} from '../broadcast/index.js';
+import type { CacheInvalidationPayload } from '../generic/CacheInvalidationResolver.js';
+import {
+    GetSessionStatusTopic,
+    PUSH_STATUS_UPDATES_TOPIC,
+    ParseStatusUpdateMessage,
+    PublishStatusUpdate,
+    ShouldReplicateStatusUpdate,
+    type PushStatusNotificationPayload,
+} from '../generic/PushStatusResolver.js';
+import { CreateSessionRoutingPubSub, PubSubManager } from '../generic/PubSubManager.js';
+import {
+    ResolveServerRole,
+    ShouldRunBackgroundWorkers,
+    ShouldServeInteractiveTraffic,
+} from '../serverRoleConfigUnits.js';
+
+function makeUser(id: string, roleIds: string[]): UserInfo {
+    return {
+        ID: id,
+        Name: `User ${id}`,
+        Email: `${id}@example.com`,
+        UserRoles: roleIds.map((r) => ({ UserID: id, RoleID: r, RoleName: r })),
+    } as unknown as UserInfo;
+}
+
+function makePayload(overrides: Partial<CacheInvalidationPayload> = {}): CacheInvalidationPayload {
+    return {
+        entityName: 'Invoices',
+        primaryKeyValues: '[{"FieldName":"ID","Value":"inv-1"}]',
+        action: 'save',
+        sourceServerId: 'srv-1',
+        timestamp: new Date('2026-10-20T12:00:00Z'),
+        recordData: '{"ID":"inv-1","Total":500}',
+        ...overrides,
+    };
+}
+
+describe('CacheInvalidationBroadcastManager & SequencedRoleBucketBroadcastProvider (Topologies 1 & 2)', () => {
+    let provider: SequencedRoleBucketBroadcastProvider;
+
+    beforeEach(() => {
+        provider = CacheInvalidationBroadcastManager.Instance.Configure({
+            provider: 'SequencedRoleBucket',
+            ringBufferSize: 5,
+            excludedEntities: ['MJ: Audit Logs'],
+        }) as SequencedRoleBucketBroadcastProvider;
+        provider.ResetStateForTesting();
+    });
+
+    it('defaults to SequencedRoleBucket and stamps monotonically increasing sequences', () => {
+        expect(provider.Topology).toBe('SequencedRoleBucket');
+        expect(provider.CurrentSequence).toBe(0);
+
+        const p1 = provider.RecordInvalidation(makePayload({ primaryKeyValues: 'pk-1' }));
+        const p2 = provider.RecordInvalidation(makePayload({ primaryKeyValues: 'pk-2' }));
+
+        expect(p1.sequence).toBe(1);
+        expect(p2.sequence).toBe(2);
+        expect(provider.CurrentSequence).toBe(2);
+        expect(provider.BufferedEventCount).toBe(2);
+    });
+
+    it('suppresses excluded high-churn entities from sequencing and broadcast', () => {
+        expect(provider.ShouldBroadcastEntity('MJ: Audit Logs')).toBe(false);
+        expect(provider.ShouldBroadcastEntity('Invoices')).toBe(true);
+
+        const ignored = provider.RecordInvalidation(makePayload({ entityName: 'MJ: Audit Logs' }));
+        expect(ignored.sequence).toBeUndefined();
+        expect(provider.CurrentSequence).toBe(0);
+    });
+
+    it('computes canonical, order-independent role fingerprints and memoizes per user object', () => {
+        const u1 = makeUser('u1', ['Role-B', 'role-a']);
+        const u2 = makeUser('u2', ['ROLE-A', '  role-b ']);
+
+        const fp1 = provider.GetRoleFingerprint(u1);
+        const fp2 = provider.GetRoleFingerprint(u2);
+
+        expect(fp1).toBe('roles:role-a|role-b');
+        expect(fp2).toBe('roles:role-a|role-b');
+        // Second call hits WeakMap cache
+        expect(provider.GetRoleFingerprint(u1)).toBe(fp1);
+    });
+
+    it('coalesces permission & RLS evaluation to O(Roles) instead of O(Subscribers)', () => {
+        const getUserPermisionsSpy = vi.fn((user: UserInfo) => {
+            const hasDeniedOnly = user.UserRoles.every((r) => r.RoleID === 'role-none');
+            return { CanRead: !hasDeniedOnly };
+        });
+
+        const fakeEntity = {
+            Name: 'Invoices',
+            GetUserPermisions: getUserPermisionsSpy,
+            Permissions: [
+                { RoleID: 'role-open', CanRead: true, Type: 'Allow', ReadRLSFilterID: null },
+                { RoleID: 'role-rls', CanRead: true, Type: 'Allow', ReadRLSFilterID: 'rls-filter-1' },
+                { RoleID: 'role-none', CanRead: false, Type: 'Allow', ReadRLSFilterID: null },
+            ],
+        } as unknown as EntityInfo;
+
+        vi.spyOn(provider, 'ResolveEntityForPayload').mockReturnValue(fakeEntity);
+        const rlsSpy = vi.spyOn(provider, 'ReadIsRowFiltered');
+
+        const payload = makePayload();
+
+        // Create 300 subscribers across only 3 distinct role buckets (100 per bucket)
+        const openUsers = Array.from({ length: 100 }, (_, i) => makeUser(`open-${i}`, ['role-open']));
+        const rlsUsers = Array.from({ length: 100 }, (_, i) => makeUser(`rls-${i}`, ['role-rls']));
+        const deniedUsers = Array.from({ length: 100 }, (_, i) => makeUser(`denied-${i}`, ['role-none']));
+
+        for (const u of openUsers) {
+            expect(provider.EvaluateEntityReadAccess(payload, u)).toBe(true);
+            const shaped = provider.ShapeEventForSubscriber(payload, u, fakeEntity);
+            expect(shaped.PrimaryKeyValues).toBe(payload.primaryKeyValues);
+            expect(shaped.RecordData).toBe(payload.recordData);
+        }
+
+        for (const u of rlsUsers) {
+            expect(provider.EvaluateEntityReadAccess(payload, u)).toBe(true);
+            const shaped = provider.ShapeEventForSubscriber(payload, u, fakeEntity);
+            expect(shaped.PrimaryKeyValues).toBeUndefined();
+            expect(shaped.RecordData).toBeUndefined();
+        }
+
+        for (const u of deniedUsers) {
+            expect(provider.EvaluateEntityReadAccess(payload, u)).toBe(false);
+        }
+
+        // Despite 300 subscribers, GetUserPermisions ran only 3 times (once per unique role bucket)
+        // and ReadIsRowFiltered ran only 2 times (for the 2 allowed role buckets)!
+        expect(getUserPermisionsSpy).toHaveBeenCalledTimes(3);
+        expect(rlsSpy).toHaveBeenCalledTimes(2);
+    });
+
+    it('serves delta catch-up from the circular ring buffer and coalesces duplicate PK updates', () => {
+        const fakeEntity = {
+            Name: 'Invoices',
+            GetUserPermisions: () => ({ CanRead: true }),
+            Permissions: [{ RoleID: 'role-open', CanRead: true, Type: 'Allow', ReadRLSFilterID: null }],
+        } as unknown as EntityInfo;
+        vi.spyOn(provider, 'ResolveEntityForPayload').mockReturnValue(fakeEntity);
+
+        const user = makeUser('u1', ['role-open']);
+
+        // Record 4 events (two on inv-1, one on inv-2, one on inv-1 again)
+        provider.RecordInvalidation(makePayload({ primaryKeyValues: 'inv-1', recordData: '{"v":1}' })); // seq 1
+        provider.RecordInvalidation(makePayload({ primaryKeyValues: 'inv-2', recordData: '{"v":2}' })); // seq 2
+        provider.RecordInvalidation(makePayload({ primaryKeyValues: 'inv-1', recordData: '{"v":3}' })); // seq 3
+
+        const catchUp = provider.GetChangesSince(0, user);
+        expect(catchUp.RequiresFullRefresh).toBe(false);
+        expect(catchUp.CurrentSequence).toBe(3);
+        // inv-1 (seq 1 and seq 3) coalesced to latest (seq 3), so 2 events total
+        expect(catchUp.Events).toHaveLength(2);
+        const inv1Event = catchUp.Events.find((e) => e.PrimaryKeyValues === 'inv-1');
+        expect(inv1Event?.RecordData).toBe('{"v":3}');
+        expect(inv1Event?.Sequence).toBe(3);
+    });
+
+    it('signals RequiresFullRefresh when sinceSequence has been evicted from the circular ring buffer', () => {
+        const fakeEntity = {
+            Name: 'Invoices',
+            GetUserPermisions: () => ({ CanRead: true }),
+            Permissions: [{ RoleID: 'role-open', CanRead: true, Type: 'Allow', ReadRLSFilterID: null }],
+        } as unknown as EntityInfo;
+        vi.spyOn(provider, 'ResolveEntityForPayload').mockReturnValue(fakeEntity);
+
+        const user = makeUser('u1', ['role-open']);
+
+        // Ring buffer size is 5; push 7 events so sequences 1 and 2 are overwritten (oldest in buffer is 3)
+        for (let i = 1; i <= 7; i++) {
+            provider.RecordInvalidation(makePayload({ primaryKeyValues: `inv-${i}` }));
+        }
+
+        // Requesting sinceSequence = 1 (missed seq 2, which was evicted) -> RequiresFullRefresh: true
+        const evictedCatchUp = provider.GetChangesSince(1, user);
+        expect(evictedCatchUp.RequiresFullRefresh).toBe(true);
+        expect(evictedCatchUp.Events).toHaveLength(0);
+
+        // Requesting sinceSequence = 2 (oldest needed is seq 3, still in buffer) -> RequiresFullRefresh: false
+        const validCatchUp = provider.GetChangesSince(2, user);
+        expect(validCatchUp.RequiresFullRefresh).toBe(false);
+        expect(validCatchUp.Events).toHaveLength(5);
+    });
+});
+
+describe('Topology 3 Cloud Multiplexer Providers (AzureWebPubSub, AWSIoTCore, GCPPubSub)', () => {
+    afterEach(() => {
+        CacheInvalidationBroadcastManager.Instance.Configure({ provider: 'SequencedRoleBucket' });
+    });
+
+    it('AzureWebPubSubBroadcastProvider negotiates signed JWT URLs and publishes role-shaped group messages', async () => {
+        const azureProvider = CacheInvalidationBroadcastManager.Instance.Configure({
+            provider: 'AzureWebPubSub',
+            azureWebPubSub: {
+                endpoint: 'https://mj-test.webpubsub.azure.com',
+                hubName: 'mj_hub',
+                accessKey: 'test-secret-access-key-123456',
+                tokenTtlMinutes: 30,
+            },
+        }) as AzureWebPubSubBroadcastProvider;
+
+        expect(azureProvider).toBeInstanceOf(AzureWebPubSubBroadcastProvider);
+        expect(azureProvider.Topology).toBe('AzureWebPubSub');
+
+        const user = makeUser('u-azure', ['Role-Admin', 'Role-Finance']);
+        const negotiated = await azureProvider.NegotiateClientConnection(user);
+        expect(negotiated.Provider).toBe('AzureWebPubSub');
+        expect(negotiated.Url).toContain('wss://mj-test.webpubsub.azure.com/client/hubs/mj_hub?access_token=');
+        expect(negotiated.Token).toBeDefined();
+        expect(negotiated.Groups).toEqual(['mj-role-role-admin', 'mj-role-role-finance']);
+
+        const published: AzureWebPubSubGroupMessage[] = [];
+        azureProvider.SetGroupPublisher(async (msg) => {
+            published.push(msg);
+        });
+
+        const fakeEntity = {
+            Name: 'Invoices',
+            GetUserPermisions: () => ({ CanRead: true }),
+            Permissions: [
+                { RoleID: 'role-admin', CanRead: true, Type: 'Allow', ReadRLSFilterID: null },
+                { RoleID: 'role-rls', CanRead: true, Type: 'Allow', ReadRLSFilterID: 'rls-1' },
+            ],
+        } as unknown as EntityInfo;
+        vi.spyOn(azureProvider, 'ResolveEntityForPayload').mockReturnValue(fakeEntity);
+
+        azureProvider.RecordInvalidation(makePayload());
+        await new Promise((r) => setTimeout(r, 10));
+
+        expect(published).toHaveLength(2);
+        const adminMsg = published.find((m) => m.GroupName === 'mj-role-role-admin');
+        const rlsMsg = published.find((m) => m.GroupName === 'mj-role-role-rls');
+        expect(adminMsg?.Event.PrimaryKeyValues).toBeDefined();
+        expect(rlsMsg?.Event.PrimaryKeyValues).toBeUndefined();
+    });
+
+    it('AWSIoTCoreBroadcastProvider negotiates SigV4 presigned MQTT URLs and publishes role topics', async () => {
+        const awsProvider = CacheInvalidationBroadcastManager.Instance.Configure({
+            provider: 'AWSIoTCore',
+            awsIoTCore: {
+                endpoint: 'a1b2c3-ats.iot.us-east-1.amazonaws.com',
+                region: 'us-east-1',
+                topicPrefix: 'mj/prod/cache',
+                accessKeyId: 'AKIAIOSFODNN7EXAMPLE',
+                secretAccessKey: 'wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY',
+            },
+        }) as AWSIoTCoreBroadcastProvider;
+
+        expect(awsProvider).toBeInstanceOf(AWSIoTCoreBroadcastProvider);
+        const user = makeUser('u-aws', ['role-ops']);
+        const negotiated = await awsProvider.NegotiateClientConnection(user);
+        expect(negotiated.Provider).toBe('AWSIoTCore');
+        expect(negotiated.Url).toContain('wss://a1b2c3-ats.iot.us-east-1.amazonaws.com/mqtt?X-Amz-Algorithm=AWS4-HMAC-SHA256');
+        expect(negotiated.Groups).toEqual(['mj/prod/cache/roles/role-ops']);
+
+        const published: AWSIoTCoreTopicMessage[] = [];
+        awsProvider.SetTopicPublisher(async (msg) => {
+            published.push(msg);
+        });
+        const fakeEntity = {
+            Name: 'Invoices',
+            GetUserPermisions: () => ({ CanRead: true }),
+            Permissions: [{ RoleID: 'role-ops', CanRead: true, Type: 'Allow', ReadRLSFilterID: null }],
+        } as unknown as EntityInfo;
+        vi.spyOn(awsProvider, 'ResolveEntityForPayload').mockReturnValue(fakeEntity);
+
+        awsProvider.RecordInvalidation(makePayload());
+        await new Promise((r) => setTimeout(r, 10));
+        expect(published).toHaveLength(1);
+        expect(published[0].Topic).toBe('mj/prod/cache/roles/role-ops');
+    });
+
+    it('GCPPubSubBroadcastProvider negotiates gateway tokens and publishes Pub/Sub topic messages', async () => {
+        const gcpProvider = CacheInvalidationBroadcastManager.Instance.Configure({
+            provider: 'GCPPubSub',
+            gcpPubSub: {
+                projectId: 'mj-cloud-prod',
+                topicPrefix: 'mj-invalidation',
+                gatewayUrl: 'https://cache-gw.run.app/ws',
+                signingSecret: 'gcp-gateway-secret-key',
+            },
+        }) as GCPPubSubBroadcastProvider;
+
+        expect(gcpProvider).toBeInstanceOf(GCPPubSubBroadcastProvider);
+        const user = makeUser('u-gcp', ['role-analyst']);
+        const negotiated = await gcpProvider.NegotiateClientConnection(user);
+        expect(negotiated.Provider).toBe('GCPPubSub');
+        expect(negotiated.Url).toContain('wss://cache-gw.run.app/ws?token=');
+        expect(negotiated.Groups).toEqual(['projects/mj-cloud-prod/topics/mj-invalidation-role-role-analyst']);
+
+        const published: GCPPubSubTopicMessage[] = [];
+        gcpProvider.SetTopicPublisher(async (msg) => {
+            published.push(msg);
+        });
+        const fakeEntity = {
+            Name: 'Invoices',
+            GetUserPermisions: () => ({ CanRead: true }),
+            Permissions: [{ RoleID: 'role-analyst', CanRead: true, Type: 'Allow', ReadRLSFilterID: null }],
+        } as unknown as EntityInfo;
+        vi.spyOn(gcpProvider, 'ResolveEntityForPayload').mockReturnValue(fakeEntity);
+
+        gcpProvider.RecordInvalidation(makePayload());
+        await new Promise((r) => setTimeout(r, 10));
+        expect(published).toHaveLength(1);
+        expect(published[0].TopicName).toBe('projects/mj-cloud-prod/topics/mj-invalidation-role-role-analyst');
+    });
+});
+
+describe('PushStatusResolver O(1) session routing and WeakMap JSON memoization', () => {
+    it('routes session-specific updates to PUSH_STATUS_UPDATES:session:<id> and wildcard updates to PUSH_STATUS_UPDATES', async () => {
+        const rawPublish = vi.fn(async () => undefined);
+        const rawPubSub: PubSubEngine = {
+            publish: rawPublish,
+            subscribe: vi.fn(),
+            unsubscribe: vi.fn(),
+            asyncIterator: vi.fn(),
+        } as unknown as PubSubEngine;
+
+        PubSubManager.Instance.SetPubSubEngine(rawPubSub);
+        const routedPubSub = PubSubManager.Instance.PubSubEngine!;
+
+        PublishStatusUpdate(routedPubSub, {
+            sessionId: 'tab-abc',
+            ownerUserId: 'user-1',
+            message: '{"type":"Progress"}',
+        });
+
+        PublishStatusUpdate(routedPubSub, {
+            sessionId: '*',
+            ownerUserId: 'user-1',
+            message: '{"type":"Broadcast"}',
+        });
+
+        expect(rawPublish).toHaveBeenCalledTimes(2);
+        expect(rawPublish).toHaveBeenNthCalledWith(
+            1,
+            GetSessionStatusTopic('tab-abc'),
+            expect.objectContaining({ sessionId: 'tab-abc' })
+        );
+        expect(rawPublish).toHaveBeenNthCalledWith(
+            2,
+            PUSH_STATUS_UPDATES_TOPIC,
+            expect.objectContaining({ sessionId: '*' })
+        );
+    });
+
+    it('memoizes JSON.parse per PushStatusNotificationPayload object via WeakMap', () => {
+        const payload: PushStatusNotificationPayload = {
+            sessionId: 'tab-1',
+            ownerUserId: 'u-1',
+            message: JSON.stringify({ type: 'StreamingContent', step: 1 }),
+        };
+
+        const parseSpy = vi.spyOn(JSON, 'parse');
+        try {
+            const first = ParseStatusUpdateMessage(payload);
+            const second = ParseStatusUpdateMessage(payload);
+            const shouldReplicate = ShouldReplicateStatusUpdate(payload.message, payload);
+
+            expect(first).toBe(second);
+            expect(shouldReplicate).toBe(false);
+            expect(parseSpy).toHaveBeenCalledTimes(1);
+        } finally {
+            parseSpy.mockRestore();
+        }
+    });
+});
+
+describe('ServerRole configuration units (Pillar 4)', () => {
+    it('resolves all, api, and worker roles case-insensitively and defaults to all', () => {
+        expect(ResolveServerRole(undefined)).toBe('all');
+        expect(ResolveServerRole('')).toBe('all');
+        expect(ResolveServerRole('  API ')).toBe('api');
+        expect(ResolveServerRole('WORKER')).toBe('worker');
+        expect(ResolveServerRole('all')).toBe('all');
+        expect(() => ResolveServerRole('invalid-role')).toThrow(/Invalid MJ_SERVER_ROLE/);
+    });
+
+    it('correctly gates background workers and interactive traffic by role', () => {
+        expect(ShouldRunBackgroundWorkers('all')).toBe(true);
+        expect(ShouldRunBackgroundWorkers('worker')).toBe(true);
+        expect(ShouldRunBackgroundWorkers('api')).toBe(false);
+
+        expect(ShouldServeInteractiveTraffic('all')).toBe(true);
+        expect(ShouldServeInteractiveTraffic('api')).toBe(true);
+        expect(ShouldServeInteractiveTraffic('worker')).toBe(false);
+    });
+});