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

package/src/__tests__/resolverBase.fls.test.ts

@@ -11,7 +11,7 @@
  * load-truth-from-DB branch so denied fields hold real values a stripped SetMany never
  * touches.
  */
-import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { describe, it, expect, vi, beforeEach, beforeAll, afterAll } from 'vitest';
 
 // ─── Hoisted mocks ────────────────────────────────────────────────────────
 const { mockUserCacheUsers } = vi.hoisted(() => ({
@@ -116,7 +116,7 @@ vi.mock('@memberjunction/core-entities', () => ({}));
 
 // ─── Import after mocks ──────────────────────────────────────────────────
 import { ResolverBase } from '../generic/ResolverBase';
-import { EntityInfo, UserInfo, UserRoleInfo } from '@memberjunction/core';
+import { EntityInfo, Metadata, RowLevelSecurityFilterInfo, UserInfo, UserRoleInfo } from '@memberjunction/core';
 
 // ─── Metadata builders (mirrors MJCore's fieldSecurity.enforcement tests) ──
 
@@ -192,8 +192,9 @@ class TestResolver extends ResolverBase {
         return this.StripDeniedReadFieldsFromClientInput(entityInfo, userInfo, input, clientNewValues);
     }
 
-    public TestMustLoadTruth(entityInfo: EntityInfo, input: ClientInput, hasDeniedReadFields: boolean, hasNarrowedAuditPayload: boolean): boolean {
-        return this.MustLoadTruthFromDatabase(entityInfo, input, hasDeniedReadFields, hasNarrowedAuditPayload);
+    /** The user defaults to HR, whose permission rows carry no row filter; pass null for a missing user. */
+    public TestMustLoadTruth(entityInfo: EntityInfo, input: ClientInput, hasDeniedReadFields: boolean, hasNarrowedAuditPayload: boolean, user: UserInfo | null = buildUser([HR_ROLE_ID])): boolean {
+        return this.MustLoadTruthFromDatabase(entityInfo, input, hasDeniedReadFields, hasNarrowedAuditPayload, user ?? undefined);
     }
 }
 
@@ -481,3 +482,85 @@ describe('ResolverBase.MustLoadTruthFromDatabase', () => {
         expect(resolver.TestMustLoadTruth(new EntityInfo(tracked), withOldValues(), false, false)).toBe(true);
     });
 });
+
+/**
+ * #4919: a caller under an Update row filter must not be hydrated from its own OldValues.
+ *
+ * The save's post-image RLS check skips its query when no column the filter reads is dirty. Hydrated
+ * from OldValues, "dirty" is whatever the client claims: an Intern bound to `Status = 'Draft'` sends
+ * Status = 'Published' and claims 'Published' as the old value too, so Status is clean, the check is
+ * skipped, and the update moves the row out of the Intern's scope.
+ */
+describe('ResolverBase.MustLoadTruthFromDatabase: Update row filters (#4919)', () => {
+    const DRAFTS_ONLY = 'F0000000-0000-0000-0000-000000004919';
+    let resolver: TestResolver;
+    let savedProvider: typeof Metadata.Provider;
+
+    beforeAll(() => {
+        savedProvider = Metadata.Provider;
+        Metadata.Provider = {
+            Entities: [],
+            RowLevelSecurityFilters: [new RowLevelSecurityFilterInfo({ ID: DRAFTS_ONLY, Name: 'Drafts only', FilterText: "Status = 'Draft'" })],
+        } as unknown as typeof Metadata.Provider;
+    });
+    afterAll(() => {
+        Metadata.Provider = savedProvider;
+    });
+    beforeEach(() => {
+        resolver = new TestResolver();
+    });
+
+    /** Untracked, no field security: the OldValues shortcut is open unless the row filter closes it. */
+    function entityWithInternFilter(filter: { UpdateRLSFilterID?: string; ReadRLSFilterID?: string }): EntityInfo {
+        const init = employeeEntityInit(false);
+        init['TrackRecordChanges'] = false;
+        init['Permissions'] = [
+            { EntityID: ENTITY_ID, RoleID: HR_ROLE_ID, CanCreate: true, CanRead: true, CanUpdate: true, CanDelete: true },
+            { EntityID: ENTITY_ID, RoleID: INTERN_ROLE_ID, CanCreate: true, CanRead: true, CanUpdate: true, CanDelete: true, ...filter },
+        ];
+        return new EntityInfo(init);
+    }
+
+    const claimsNewStatusAsOld = (): ClientInput => ({
+        ID: '1',
+        Status: 'Published',
+        OldValues___: [
+            { Key: 'ID', Value: '1' },
+            { Key: 'Status', Value: 'Published' },
+        ],
+    });
+
+    it('loads the stored row for a caller under an Update row filter, whatever OldValues claim', () => {
+        const entity = entityWithInternFilter({ UpdateRLSFilterID: DRAFTS_ONLY });
+        expect(resolver.TestMustLoadTruth(entity, claimsNewStatusAsOld(), false, false, buildUser([INTERN_ROLE_ID]))).toBe(true);
+    });
+
+    it('keeps the shortcut for a caller with no Update row filter, on the same entity', () => {
+        const entity = entityWithInternFilter({ UpdateRLSFilterID: DRAFTS_ONLY });
+        expect(resolver.TestMustLoadTruth(entity, claimsNewStatusAsOld(), false, false, buildUser([HR_ROLE_ID]))).toBe(false);
+        // A role without the filter exempts the user from it (roles are additive).
+        expect(resolver.TestMustLoadTruth(entity, claimsNewStatusAsOld(), false, false, buildUser([INTERN_ROLE_ID, HR_ROLE_ID]))).toBe(false);
+    });
+
+    it('loads the stored row when the user is missing, instead of throwing or skipping the filter', () => {
+        const entity = entityWithInternFilter({ UpdateRLSFilterID: DRAFTS_ONLY });
+        expect(resolver.TestMustLoadTruth(entity, claimsNewStatusAsOld(), false, false, null)).toBe(true);
+    });
+
+    it('loads the stored row under an API-key Update row filter, even for a role-exempt user', () => {
+        const entity = entityWithInternFilter({});
+        const keyBound = (permissionType: 'Read' | 'Update') => {
+            const user = buildUser([HR_ROLE_ID]); // no role filter: only the key binding narrows this caller
+            user.APIKeyRowFilters = [{ EntityID: ENTITY_ID, PermissionType: permissionType, FilterID: DRAFTS_ONLY }];
+            return user;
+        };
+        expect(resolver.TestMustLoadTruth(entity, claimsNewStatusAsOld(), false, false, buildUser([HR_ROLE_ID]))).toBe(false);
+        expect(resolver.TestMustLoadTruth(entity, claimsNewStatusAsOld(), false, false, keyBound('Update'))).toBe(true);
+        expect(resolver.TestMustLoadTruth(entity, claimsNewStatusAsOld(), false, false, keyBound('Read'))).toBe(false);
+    });
+
+    it('ignores a Read-only row filter: only the Update filter gates this save', () => {
+        const entity = entityWithInternFilter({ ReadRLSFilterID: DRAFTS_ONLY });
+        expect(resolver.TestMustLoadTruth(entity, claimsNewStatusAsOld(), false, false, buildUser([INTERN_ROLE_ID]))).toBe(false);
+    });
+});

package/src/__tests__/serverExtensionHostOverlay.test.ts

@@ -0,0 +1,66 @@
+/**
+ * A host mj.config.cjs serverExtensions[] entry may be a partial OVERLAY of an extension an Open App
+ * package publishes: only DriverClass is required. The schema used to require RootPath and default
+ * Enabled to true, so `{ DriverClass, OwnsCORS: false }` failed config parsing at startup, and an
+ * overlay that omitted Enabled re-enabled an extension its package ships disabled. Completeness is
+ * checked after the merge instead.
+ */
+import { describe, it, expect, vi } from 'vitest';
+
+// config.ts evaluates `configInfo = LoadConfig()` at module load, and it rejects a configuration
+// carrying no database credentials. Stubbing only the cosmiconfig search lets the module import so the
+// REAL ServerExtensionSchema is under test (same pattern as newUserRolesDefault.test.ts).
+vi.mock('cosmiconfig', () => ({
+    cosmiconfigSync: () => ({
+        search: () => ({
+            filepath: '/test/mj.config.cjs',
+            isEmpty: false,
+            config: { dbUsername: 'test-user', dbPassword: 'test-password', dbDatabase: 'test-db' },
+        }),
+    }),
+}));
+
+import { MergeServerExtensionConfigs, PrepareServerExtensionConfigs } from '@memberjunction/server-extensions-core';
+import type { ServerExtensionConfig } from '@memberjunction/server-extensions-core';
+import { ServerExtensionSchema } from '../config.js';
+
+const published: ServerExtensionConfig = {
+    Enabled: true,
+    DriverClass: 'BallotEdge',
+    RootPath: '/vote',
+    OwnsCORS: true,
+    Settings: { RateLimitMax: 20 },
+};
+
+describe('host serverExtensions[] overlay schema', () => {
+    it('accepts an overlay that names only DriverClass and the fields it overrides', () => {
+        const parsed = ServerExtensionSchema.safeParse({ DriverClass: 'BallotEdge', OwnsCORS: false });
+        expect(parsed.success).toBe(true);
+        expect(parsed.success && parsed.data.RootPath).toBeUndefined();
+        expect(parsed.success && parsed.data.Enabled).toBeUndefined();
+    });
+
+    it('merges the overlay onto the published entry without losing RootPath or Enabled', () => {
+        const overlay = ServerExtensionSchema.parse({ DriverClass: 'BallotEdge', OwnsCORS: false, Settings: { RateLimitMax: 2000 } });
+        const [merged] = MergeServerExtensionConfigs([published], [overlay as ServerExtensionConfig]);
+        expect(merged).toMatchObject({ DriverClass: 'BallotEdge', RootPath: '/vote', Enabled: true, OwnsCORS: false });
+        expect(merged.Settings).toEqual({ RateLimitMax: 2000 });
+    });
+
+    it('does not re-enable an extension the package ships disabled', () => {
+        const overlay = ServerExtensionSchema.parse({ DriverClass: 'BallotEdge', Settings: { RateLimitMax: 5 } });
+        const [merged] = MergeServerExtensionConfigs([{ ...published, Enabled: false }], [overlay as ServerExtensionConfig]);
+        expect(merged.Enabled).toBe(false);
+    });
+
+    it('still rejects a host-only entry without a RootPath, after the merge', () => {
+        const overlay = ServerExtensionSchema.parse({ DriverClass: 'NotPublishedAnywhere' });
+        const problems: string[] = [];
+        const prepared = PrepareServerExtensionConfigs(
+            MergeServerExtensionConfigs([published], [overlay as ServerExtensionConfig]),
+            { onInvalid: (message: string) => problems.push(message) },
+        );
+        expect(prepared.map(c => c.DriverClass)).toEqual(['BallotEdge']);
+        expect(problems.some(p => p.includes('NotPublishedAnywhere') && p.includes('RootPath is empty'))).toBe(true);
+    });
+});

package/src/__tests__/serverExtensionReservedRoots.test.ts

@@ -1,8 +1,8 @@
 /**
  * Pins the reserved-root set passed into prepareServerExtensionConfigs.
- * A new public mount in index.ts / a drifted `*_MOUNT_PATH` constant is a
- * contract failure — this file reads those sources as text so it never loads
- * `config.ts`.
+ * A drifted `*_MOUNT_PATH` constant is a contract failure — this file reads those
+ * sources as text so it never loads `config.ts`. That every core mount is reserved
+ * is checked against the real mounts in apiRootBoot.test.ts.
  */
 import { describe, it, expect } from 'vitest';
 import { readFileSync } from 'node:fs';
@@ -26,11 +26,6 @@ function exportedStringConst(relativeFile: string, name: string): string {
     return match[1];
 }
 
-function indexContainsLiteralPath(path: string): boolean {
-    const src = readFileSync(join(SRC, 'index.ts'), 'utf8');
-    return src.includes(`'${path}'`) || src.includes(`\`${path}\``) || src.includes(path.replace(/^\//, ''));
-}
-
 describe('coreReservedServerExtensionRoots', () => {
     it('stays in lockstep with exported *_MOUNT_PATH constants', () => {
         expect(CORE_CONSTANT_RESERVED_SERVER_EXTENSION_ROOTS).toEqual([
@@ -40,90 +35,11 @@ describe('coreReservedServerExtensionRoots', () => {
         ]);
     });
 
-    it('includes the literal pre-auth paths serve() registers without a constant', () => {
-        const indexSrc = readFileSync(join(SRC, 'index.ts'), 'utf8');
-        for (const path of CORE_STATIC_RESERVED_SERVER_EXTENSION_ROOTS) {
-            if (path === '/health') {
-                expect(indexSrc, `${path} missing from serve()`).toContain("'/health/extensions'");
-            } else if (path === '/realtime') {
-                expect(indexSrc, `${path} missing from serve()`).toMatch(/REALTIME_SDP_EXCHANGE_PATH|'\/realtime'/);
-            } else if (path === '/realtime-proxy') {
-                expect(indexSrc, `${path} missing from serve()`).toContain('/realtime-proxy');
-            } else {
-                expect(indexSrc, `${path} missing from serve()`).toContain(`'${path}'`);
-            }
-        }
-        expect(indexContainsLiteralPath('/healthcheck')).toBe(true);
-    });
-
-    it('structurally guarantees every pre-auth app.use / app.get / app.post mount in index.ts is reserved', () => {
-        const indexSrc = readFileSync(join(SRC, 'index.ts'), 'utf8');
-        const authMiddlewareIndex = indexSrc.indexOf('app.use(CreateUnifiedAuthMiddleware');
-        expect(authMiddlewareIndex).toBeGreaterThan(0);
-        const preAuthSrc = indexSrc.substring(0, authMiddlewareIndex);
-
-        const mountRegex = /app\.(?:use|get|post)\s*\(\s*([^,\s)]+)/g;
-        const reservedRoots = CoreReservedServerExtensionRoots('/');
-
-        // Explicit allowlist of known non-path middleware mounts (e.g. app.use(mw), app.use(cors()), app.use(compression(...)))
-        const knownNonPathTokens = [
-            'cors',
-            'express.',
-            'compression',
-            'cookieParser',
-            'CreateUnifiedAuthMiddleware',
-            'mw',
-        ];
-        const isKnownNonPath = (t: string): boolean =>
-            knownNonPathTokens.some(k => t === k || t.startsWith(k));
-
-        // Strip single-line and multi-line comments so comments like `app.use(...)` are not treated as code
-        const cleanPreAuthSrc = preAuthSrc.replace(/\/\*[\s\S]*?\*\/|\/\/.*/g, '');
-
-        let match: RegExpExecArray | null;
-        const mountedTokens: string[] = [];
-        while ((match = mountRegex.exec(cleanPreAuthSrc)) !== null) {
-            mountedTokens.push(match[1].trim());
-        }
-
-        expect(mountedTokens.length).toBeGreaterThan(0);
-
-        const knownConstants: Record<string, string> = {
-            REALTIME_SDP_EXCHANGE_PATH: '/realtime',
-            MAGIC_LINK_MOUNT_PATH: '/magic-link',
-            WIDGET_MOUNT_PATH: '/widget',
-            AUTH_CATALOG_MOUNT_PATH: '/auth',
-        };
-
-        for (const token of mountedTokens) {
-            const isLiteralPath = token.startsWith("'") || token.startsWith('"') || token.startsWith('`');
-            const isPathConstant = /^[A-Z0-9_]+_PATH$/.test(token) || token in knownConstants;
-            if (!isLiteralPath && !isPathConstant) {
-                if (isKnownNonPath(token)) {
-                    continue;
-                }
-                throw new Error(`Unrecognized pre-auth mount argument '${token}' in index.ts. If this is a non-path middleware, add it to knownNonPathTokens; if it is a route, reserve its prefix or map its constant.`);
-            }
-
-            let pathPrefix: string;
-            if (isLiteralPath) {
-                pathPrefix = token.slice(1, -1);
-            } else if (token in knownConstants) {
-                pathPrefix = knownConstants[token];
-            } else {
-                throw new Error(`Unrecognized pre-auth mount constant '${token}' in index.ts. If this is a new pre-auth route, map its constant or reserve its prefix.`);
-            }
-
-            const isCovered = reservedRoots.some(root => pathPrefix === root || pathPrefix.startsWith(`${root}/`));
-            expect(isCovered, `Pre-auth mount '${pathPrefix}' (from token '${token}') must be covered by reserved roots`).toBe(true);
-        }
-    });
-
-    it('includes graphqlRootPath and every core mount', () => {
-        const roots = CoreReservedServerExtensionRoots('/api');
+    it('includes every core mount, and no longer graphqlRootPath', () => {
+        const roots = CoreReservedServerExtensionRoots();
+        expect(roots).not.toContain('/api');
         expect(roots).toEqual(
             expect.arrayContaining([
-                '/api',
                 '/auth',
                 '/magic-link',
                 '/widget',
@@ -139,7 +55,7 @@ describe('coreReservedServerExtensionRoots', () => {
     });
 
     it('closes the F-M2 bypasses: cased /auth and sibling /healthcheck', () => {
-        const extra = CoreReservedServerExtensionRoots('/');
+        const extra = CoreReservedServerExtensionRoots();
         expect(validateServerExtensionRootPath('/Auth', extra)).toMatch(/reserved prefix/);
         expect(validateServerExtensionRootPath('/healthcheck', extra)).toMatch(/reserved prefix/);
         expect(validateServerExtensionRootPath('/Healthcheck', extra)).toMatch(/reserved prefix/);
@@ -155,10 +71,9 @@ describe('coreReservedServerExtensionRoots', () => {
         expect(validateServerExtensionRootPath('/meetings/teams', extra)).toBeNull();
     });
 
-    it('reserves a non-default graphqlRootPath and its nested paths', () => {
-        const extra = CoreReservedServerExtensionRoots('/api');
-        expect(validateServerExtensionRootPath('/api', extra)).toMatch(/reserved prefix/);
-        expect(validateServerExtensionRootPath('/api/graphql', extra)).toMatch(/reserved prefix/);
-        expect(validateServerExtensionRootPath('/apiv2', extra)).toBeNull();
+    it('lets extensions sit under the GraphQL path (#5674): RootPaths are relative to MJAPI_BASE_PATH', () => {
+        const extra = CoreReservedServerExtensionRoots();
+        expect(validateServerExtensionRootPath('/api', extra)).toBeNull();
+        expect(validateServerExtensionRootPath('/forms', extra)).toBeNull();
     });
 });

package/src/__tests__/sharedCache.test.ts

@@ -0,0 +1,312 @@
+import 'reflect-metadata';
+/**
+ * Routing of shared-cache events in MJAPI: metadata notices trigger a metadata check,
+ * everything reaches LocalCacheManager, and only RunView slot changes reach browsers.
+ */
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import type { CacheChangedEvent, ProviderBase } from '@memberjunction/core';
+
+const dispatch = vi.fn();
+const publish = vi.fn();
+const startSweeper = vi.fn();
+
+/** Intervals StartUserCacheChecks handed to the user cache. */
+const userCacheInterval: number[] = [];
+
+vi.mock('@memberjunction/core', () => ({
+    CacheCategory: { RunViewCache: 'RunViewCache', RunQueryCache: 'RunQueryCache', DatasetCache: 'DatasetCache', Metadata: 'Metadata', Default: 'default' },
+    LocalCacheManager: { Instance: {
+        DispatchCacheChange: (e: CacheChangedEvent) => dispatch(e),
+        // The metadata sweep takes a fleet lease before doing any work; grant it in tests.
+        TryAcquireSharedLease: vi.fn(async () => true),
+    } },
+    LogStatusEx: vi.fn(),
+    LogError: vi.fn(),
+    BaseEngineSweeper: { Instance: { Start: (ms: number) => startSweeper(ms) } },
+}));
+vi.mock('@memberjunction/redis-provider', () => ({ RedisLocalStorageProvider: vi.fn(function (this: Record<string, unknown>, cfg: unknown) { this.cfg = cfg; }) }));
+vi.mock('../generic/PubSubManager.js', () => ({ PubSubManager: { Instance: { Publish: (...a: unknown[]) => publish(...a) } } }));
+vi.mock('../generic/CacheInvalidationResolver.js', () => ({ CACHE_INVALIDATION_TOPIC: 'CACHE_INVALIDATION' }));
+vi.mock('@memberjunction/generic-database-provider', () => ({
+  UserCache: { Instance: { StartStalenessChecks: (ms: number) => userCacheInterval.push(ms) } },
+}));
+
+import {
+    CacheManagerConfigFromSettings, CreateSharedCacheFromEnvironment, MJAPI_PUBLISH_MODES, ResolveSharedCacheTTLSeconds, RouteSharedCacheEvent,
+    StartEngineSweeper,
+    StartUserCacheChecks,
+    StartMetadataSweep,
+    WirePushStatusFanOut,
+} from '../sharedCache.js';
+import { MJGlobal } from '@memberjunction/global';
+import type { PubSubEngine } from 'type-graphql';
+import { PublishStatusUpdate, SetPushStatusPublishHook } from '../generic/PushStatusResolver.js';
+import { RedisLocalStorageProvider } from '@memberjunction/redis-provider';
+import type { CacheSettingsConfig } from '../config.js';
+
+function settings(overrides: Partial<CacheSettingsConfig>): CacheSettingsConfig {
+    return { maxMemoryMB: 150, maxPercentOfCachePerEntity: 50, maxEntryPercentOfCache: 'auto', defaultTTLSeconds: 0, evictionSweepIntervalSeconds: 300, verboseLogging: false, engineSweepIntervalSeconds: 300, ...overrides };
+}
+
+function event(overrides: Partial<CacheChangedEvent>): CacheChangedEvent {
+    return { CacheKey: 'k', Category: 'RunViewCache', Action: 'set', Timestamp: 1, SourceServerId: 'peer-server', ...overrides };
+}
+
+function provider(isNotice: boolean): ProviderBase {
+    return { HandlePeerMetadataNotice: vi.fn(() => isNotice) } as unknown as ProviderBase;
+}
+
+describe('shared cache event routing', () => {
+    beforeEach(() => {
+        dispatch.mockReset();
+        publish.mockReset();
+    });
+
+    it('publishes RunView rows in full, metadata snapshots as notices, and nothing else', () => {
+        expect(MJAPI_PUBLISH_MODES).toEqual({ RunViewCache: 'full', default: 'notice' });
+    });
+
+    it('hands a metadata notice to the provider and stops there', () => {
+        const p = provider(true);
+        RouteSharedCacheEvent(event({ Category: 'default', CacheKey: '___MJCore_Metadata_Timestamps' }), p);
+        expect(p.HandlePeerMetadataNotice).toHaveBeenCalledOnce();
+        expect(dispatch).not.toHaveBeenCalled();
+        expect(publish).not.toHaveBeenCalled();
+    });
+
+    it('dispatches a RunView change and relays it to browsers as an entity invalidation', () => {
+        RouteSharedCacheEvent(event({ CacheKey: 'MJ: AI Models|_|_|-1|0|_|_|imr:1' }), provider(false));
+        expect(dispatch).toHaveBeenCalledOnce();
+        expect(publish).toHaveBeenCalledWith('CACHE_INVALIDATION', expect.objectContaining({ entityName: 'MJ: AI Models', action: 'set', primaryKeyValues: null }));
+    });
+
+    it('does not relay other categories or category clears to browsers', () => {
+        RouteSharedCacheEvent(event({ Category: 'default', CacheKey: '___MJCore_Metadata_AllMetadata' }), provider(false));
+        RouteSharedCacheEvent(event({ Category: 'DatasetCache', CacheKey: 'ds' }), provider(false));
+        RouteSharedCacheEvent(event({ Category: 'RunViewCache', CacheKey: 'RunViewCache', Action: 'category_cleared' }), provider(false));
+        expect(dispatch).toHaveBeenCalledTimes(3);
+        expect(publish).not.toHaveBeenCalled();
+    });
+
+    it('ignores notices that arrive before the metadata provider exists', () => {
+        RouteSharedCacheEvent(event({ Category: 'default', CacheKey: '___MJCore_Metadata_Timestamps' }), undefined);
+        expect(dispatch).toHaveBeenCalledOnce();
+        expect(publish).not.toHaveBeenCalled();
+    });
+});
+
+describe('shared cache configuration', () => {
+    it('builds the provider only when REDIS_URL is set, with MJAPI publish modes', () => {
+        expect(CreateSharedCacheFromEnvironment(undefined, {})).toBeNull();
+        const provider = CreateSharedCacheFromEnvironment(settings({ verboseLogging: true, sharedCacheTTLSeconds: 120 }),
+            { REDIS_URL: 'redis://h:1', REDIS_KEY_PREFIX: 'fleet' }) as unknown as { cfg: Record<string, unknown> };
+        expect(provider).toBeInstanceOf(RedisLocalStorageProvider);
+        expect(provider.cfg).toMatchObject({
+            url: 'redis://h:1', keyPrefix: 'fleet', defaultTTLSeconds: 120, enablePubSub: true, enableLogging: true,
+            publishModes: { RunViewCache: 'full', default: 'notice' }, defaultPublishMode: 'none',
+        });
+    });
+
+    it('lets REDIS_TTL_SECONDS override the configured TTL, and ignores junk', () => {
+        expect(ResolveSharedCacheTTLSeconds(120, { REDIS_TTL_SECONDS: '60' })).toBe(60);
+        expect(ResolveSharedCacheTTLSeconds(120, { REDIS_TTL_SECONDS: '0' })).toBe(0);
+        const warn = vi.spyOn(console, 'warn').mockImplementation(() => undefined);
+        expect(ResolveSharedCacheTTLSeconds(120, { REDIS_TTL_SECONDS: 'soon' })).toBe(120);
+        warn.mockRestore();
+        expect(ResolveSharedCacheTTLSeconds(undefined, {})).toBeUndefined();
+    });
+
+    it('maps cacheSettings onto LocalCacheManager settings', () => {
+        expect(CacheManagerConfigFromSettings(settings({ maxMemoryMB: 10, maxPercentOfCachePerEntity: 20, maxEntryPercentOfCache: 40, defaultTTLSeconds: 5, evictionSweepIntervalSeconds: 7, verboseLogging: true })))
+            .toEqual({ maxSizeBytes: 10 * 1024 * 1024, maxPercentOfCachePerEntity: 20, maxEntryPercentOfCache: 40, defaultTTLMs: 5000, evictionSweepIntervalMs: 7000, verboseLogging: true });
+        expect(CacheManagerConfigFromSettings(undefined).maxSizeBytes).toBe(150 * 1024 * 1024);
+        // The per-entry ceiling reaches the cache, and an unset one is derived rather than a fixed fraction.
+        expect(CacheManagerConfigFromSettings(undefined).maxEntryPercentOfCache).toBe('auto');
+    });
+
+    it('starts the engine sweep at the configured interval, off when 0', () => {
+        startSweeper.mockReset();
+        expect(StartEngineSweeper(settings({ engineSweepIntervalSeconds: 60 }))).toBe(60_000);
+        expect(startSweeper).toHaveBeenLastCalledWith(60_000);
+        expect(StartEngineSweeper(undefined)).toBe(300_000);
+        expect(StartEngineSweeper(settings({ engineSweepIntervalSeconds: 0 }))).toBe(0);
+        expect(startSweeper).toHaveBeenLastCalledWith(0);
+    });
+
+    it('starts the user-cache staleness check at the configured interval, off when 0', () => {
+        userCacheInterval.length = 0;
+        expect(StartUserCacheChecks(settings({ userCacheCheckIntervalSeconds: 60 }))).toBe(60_000);
+        expect(StartUserCacheChecks(undefined)).toBe(300_000);
+        expect(StartUserCacheChecks(settings({ userCacheCheckIntervalSeconds: 0 }))).toBe(0);
+        expect(userCacheInterval).toEqual([60_000, 300_000, 0]);
+    });
+});
+
+/**
+ * The metadata sweep is the backstop for metadata written outside MJ — and nothing else.
+ *
+ * Metadata staleness is otherwise event-driven: a `BaseEntity` write to a member entity schedules a
+ * refresh, a peer's snapshot write publishes a notice, a CLI write clears the cache. None of those
+ * fire for raw SQL, so metadata edited directly in the database is never noticed by a running
+ * process.
+ *
+ * It must not become an unconditional poll. A recurring query prevents a serverless database from
+ * pausing, and `TrustServerCacheCompletely = true` (every MJ entity, by default) states that the
+ * event paths already cover the entity — so there is nothing a query could find.
+ */
+describe('StartMetadataSweep', () => {
+    afterEach(() => {
+        StartMetadataSweep(settings({ metadataSweepIntervalSeconds: 0 }), () => undefined);
+        vi.useRealTimers();
+    });
+
+    it('returns the configured interval, and 0 disables it', () => {
+        expect(StartMetadataSweep(settings({ metadataSweepIntervalSeconds: 45 }), () => undefined)).toBe(45_000);
+        expect(StartMetadataSweep(settings({ metadataSweepIntervalSeconds: 0 }), () => undefined)).toBe(0);
+    });
+
+    it('asks the provider NOTHING when no metadata entity declares drift', async () => {
+        vi.useFakeTimers();
+        const sweep = vi.fn();
+        const provider = {
+            MetadataMembersDeclaringDrift: () => [],
+            SweepMetadataAgainstDatabase: sweep,
+        } as unknown as ProviderBase;
+
+        StartMetadataSweep(settings({ metadataSweepIntervalSeconds: 10 }), () => provider);
+        await vi.advanceTimersByTimeAsync(10_000 * 3 + 100);
+
+        expect(sweep).not.toHaveBeenCalled();
+    });
+
+    it('sweeps when a metadata entity declares drift', async () => {
+        vi.useFakeTimers();
+        const sweep = vi.fn().mockResolvedValue({ Declared: ['MJ: Entities'], Checked: true, Refreshed: true });
+        const provider = {
+            MetadataMembersDeclaringDrift: () => ['MJ: Entities'],
+            SweepMetadataAgainstDatabase: sweep,
+        } as unknown as ProviderBase;
+
+        StartMetadataSweep(settings({ metadataSweepIntervalSeconds: 10 }), () => provider);
+        await vi.advanceTimersByTimeAsync(10_000 + 100);
+
+        expect(sweep).toHaveBeenCalled();
+    });
+});
+
+/**
+ * The push-status fan-out's WIRING (MJ #4222).
+ *
+ * `pushStatusFanOut.test.ts` covers the pieces — what is worth replicating, that every publish is
+ * stamped with the publishing instance, and every branch of `ParseReplicatedStatusUpdate`. What
+ * nothing covered is the wiring that joins them to Redis, which is the code that moved into this
+ * module: that a channel is actually subscribed, that inbound traffic is parsed against THIS
+ * process's id and handed to `PubSubManager`, that a local publish is forwarded on the same
+ * channel, and that a Redis failure degrades the feature instead of stopping the server.
+ *
+ * The parser and the publisher here are the real ones; mocking them would make these tests of the
+ * mock rather than of the wiring.
+ */
+describe('push-status fan-out wiring', () => {
+    /** A stand-in for the shared cache provider, capturing what the fan-out does to it. */
+    class FakeSharedCache {
+        public SubscribedChannel: string | undefined;
+        public Published: Array<{ channel: string; payload: string }> = [];
+        private inboundHandler: ((raw: string) => void) | undefined;
+        constructor(private subscribeFails = false) {}
+
+        public SubscribeToChannel = vi.fn(async (channel: string, handler: (raw: string) => void) => {
+            if (this.subscribeFails) {
+                throw new Error('redis is down');
+            }
+            this.SubscribedChannel = channel;
+            this.inboundHandler = handler;
+            return () => undefined;
+        });
+
+        public PublishMessage = vi.fn((channel: string, payload: string) => {
+            this.Published.push({ channel, payload });
+        });
+
+        /** Simulates Redis delivering a message on the subscribed channel. */
+        public Deliver(raw: string): void {
+            this.inboundHandler?.(raw);
+        }
+
+        public AsProvider(): RedisLocalStorageProvider {
+            return this as unknown as RedisLocalStorageProvider;
+        }
+    }
+
+    /** A PubSubEngine the real publisher can publish locally on, which these tests ignore. */
+    function localTopic(): PubSubEngine {
+        return { publish: vi.fn(async () => undefined) } as unknown as PubSubEngine;
+    }
+
+    beforeEach(() => {
+        publish.mockReset();
+        SetPushStatusPublishHook(undefined);
+    });
+    afterEach(() => {
+        SetPushStatusPublishHook(undefined);
+    });
+
+    it('subscribes to the push-status channel on the shared connection', async () => {
+        const redis = new FakeSharedCache();
+        await WirePushStatusFanOut(redis.AsProvider());
+
+        expect(redis.SubscribeToChannel).toHaveBeenCalledTimes(1);
+        expect(redis.SubscribedChannel).toBe('push-status-updates');
+    });
+
+    it("hands a PEER's update to this process's local topic, identity fields intact", async () => {
+        const redis = new FakeSharedCache();
+        await WirePushStatusFanOut(redis.AsProvider());
+
+        redis.Deliver(JSON.stringify({
+            sessionId: 'session-1', ownerUserId: 'user-1', message: 'done', SourceServerId: 'some-other-replica',
+        }));
+
+        expect(publish).toHaveBeenCalledTimes(1);
+        expect(publish).toHaveBeenCalledWith('PUSH_STATUS_UPDATES', {
+            sessionId: 'session-1', ownerUserId: 'user-1', message: 'done', SourceServerId: 'some-other-replica',
+        });
+    });
+
+    it("drops this process's own update echoed back, so a push is not delivered twice", async () => {
+        // The parser owns the comparison; this pins that the wiring gives it THIS process's id.
+        const redis = new FakeSharedCache();
+        await WirePushStatusFanOut(redis.AsProvider());
+
+        redis.Deliver(JSON.stringify({
+            sessionId: 'session-1', ownerUserId: 'user-1', message: 'done',
+            SourceServerId: MJGlobal.Instance.ProcessUUID,
+        }));
+
+        expect(publish).not.toHaveBeenCalled();
+    });
+
+    it('forwards a real local publish onto the same channel', async () => {
+        const redis = new FakeSharedCache();
+        await WirePushStatusFanOut(redis.AsProvider());
+
+        PublishStatusUpdate(localTopic(), { sessionId: 'session-9', ownerUserId: 'user-9', message: 'agent finished' });
+
+        expect(redis.Published).toHaveLength(1);
+        expect(redis.Published[0].channel).toBe('push-status-updates');
+        expect(JSON.parse(redis.Published[0].payload)).toEqual({
+            sessionId: 'session-9', ownerUserId: 'user-9', message: 'agent finished',
+            SourceServerId: MJGlobal.Instance.ProcessUUID,
+        });
+    });
+
+    it('degrades instead of stopping the server when Redis cannot subscribe', async () => {
+        const redis = new FakeSharedCache(true);
+
+        await expect(WirePushStatusFanOut(redis.AsProvider())).resolves.toBeUndefined();
+
+        // No hook may be left pointing at a connection it could not subscribe on.
+        PublishStatusUpdate(localTopic(), { sessionId: 's', ownerUserId: 'u', message: 'x' });
+        expect(redis.PublishMessage).not.toHaveBeenCalled();
+    });
+});