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

package/dist/services/TaskGraphContinuationDeliverer.js

@@ -40,7 +40,8 @@ export class TaskGraphContinuationDeliverer {
         this.contextUser = contextUser;
     }
     /**
-     * Posts the roll-up as an AI-role message in the graph's conversation.
+     * Posts the roll-up as an AI-role message in the graph's conversation, on the fork of the
+     * message that started the graph (Main when that message is in Main).
      *
      * Never throws. The dispatcher calls this inside the compare-and-swap that marks a completion
      * delivered; an error escaping would either abort that guard or leave the graph looking
@@ -55,15 +56,16 @@ export class TaskGraphContinuationDeliverer {
                 return;
             }
             const provider = await this.providerFactory.CreateProvider();
-            const conversationID = await this.resolveConversationID(params.ConversationDetailID, provider);
-            if (!conversationID) {
+            const origin = await this.resolveOrigin(params.ConversationDetailID, provider);
+            if (!origin) {
                 LogError(`[TaskGraphContinuationDeliverer] Conversation detail ${params.ConversationDetailID} could not be loaded — ` +
                     `"${params.WorkflowName}" has nowhere to post its outcome.`);
                 return;
             }
             const detail = await provider.GetEntityObject('MJ: Conversation Details', this.contextUser);
             detail.NewRecord();
-            detail.ConversationID = conversationID;
+            detail.ConversationID = origin.ConversationID;
+            detail.BranchID = origin.BranchID;
             detail.Role = 'AI';
             detail.Status = 'Complete';
             detail.HiddenToUser = false;
@@ -109,11 +111,15 @@ export class TaskGraphContinuationDeliverer {
                 await this.PostMessage(params);
                 return;
             }
+            // Run on the fork of the message that started the graph, as PostMessage posts into it:
+            // RunAgent derives the conversation from the detail, but not the fork.
+            const origin = params.ConversationDetailID ? await this.resolveOrigin(params.ConversationDetailID, provider) : null;
             await new AgentRunner().RunAgent({
                 agent,
                 conversationMessages: [{ role: ChatMessageRole.user, content: this.renderMessage(params) }],
                 contextUser: this.contextUser,
                 conversationDetailId: params.ConversationDetailID ?? undefined,
+                ConversationBranchID: origin?.BranchID ?? undefined,
                 // The load-bearing value: without it the next graph this run submits restarts the
                 // chain at zero and the cap never fires.
                 continuationDepth: params.ReinvokeDepth + 1,
@@ -134,10 +140,10 @@ export class TaskGraphContinuationDeliverer {
             }
         }
     }
-    /** The conversation a detail belongs to. */
-    async resolveConversationID(conversationDetailID, provider) {
+    /** The conversation and fork (null is Main) of the detail that started the graph; null when it cannot be loaded. */
+    async resolveOrigin(conversationDetailID, provider) {
         const detail = await provider.GetEntityObject('MJ: Conversation Details', this.contextUser);
-        return (await detail.Load(conversationDetailID)) ? detail.ConversationID : null;
+        return (await detail.Load(conversationDetailID)) ? { ConversationID: detail.ConversationID, BranchID: detail.BranchID ?? null } : null;
     }
     /**
      * Renders the outcome as Markdown.

package/dist/services/TaskGraphContinuationDeliverer.js.map

@@ -1 +1 @@
-{"version":3,"file":"TaskGraphContinuationDeliverer.js","sourceRoot":"","sources":["../../src/services/TaskGraphContinuationDeliverer.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"TaskGraphContinuationDeliverer.js","sourceRoot":"","sources":["../../src/services/TaskGraphContinuationDeliverer.ts"],"names":[],"mappings":"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"}

package/dist/services/WorkQueueHostService.d.ts

@@ -0,0 +1,36 @@
+import sql from 'mssql';
+import type { DatabaseProviderBase, IMetadataProvider, UserInfo } from '@memberjunction/core';
+import { WorkQueueEngine } from '@memberjunction/work-queue-engine';
+import type { WorkQueueHostConfig, WorkQueueProviderSource } from '@memberjunction/work-queue-engine';
+import type { WorkQueueConfig } from './workQueueConfig.js';
+export declare const WORK_QUEUE_DISABLE_ENV = "MJ_DISABLE_WORK_QUEUE_HOST";
+type EnvironmentVariables = Record<string, string | undefined>;
+export interface StartableWorkQueueHost {
+    Start(): Promise<void>;
+}
+/** Seams for tests; production uses DEFAULT_WORK_QUEUE_HOST_START_DEPENDENCIES. */
+export interface WorkQueueHostStartDependencies {
+    Env: EnvironmentVariables;
+    FindUserByEmail(email: string): UserInfo | undefined;
+    ConfigureEngine(user: UserInfo, provider: DatabaseProviderBase): Promise<WorkQueueEngine>;
+    CreateHost(config: WorkQueueHostConfig, engine: WorkQueueEngine, user: UserInfo, provider: DatabaseProviderBase, providerSource: WorkQueueProviderSource): StartableWorkQueueHost;
+}
+export declare const DEFAULT_WORK_QUEUE_HOST_START_DEPENDENCIES: WorkQueueHostStartDependencies;
+export declare function IsWorkQueueHostDisabledByEnv(env: EnvironmentVariables): boolean;
+/**
+ * Host and pid for humans reading logs; the random suffix for uniqueness — containers routinely share pid 1 and
+ * HOSTNAME is not always exported. A restart is a new instance, so a dead process's leases simply expire.
+ */
+export declare function CreateWorkQueueInstanceID(env?: EnvironmentVariables): string;
+export declare function BuildWorkQueueHostConfig(config: WorkQueueConfig, instanceID: string): WorkQueueHostConfig;
+/** A fresh SQL Server provider per delivery over the shared pool; the server provider otherwise. */
+export declare class MJServerWorkQueueProviderSource implements WorkQueueProviderSource {
+    private readonly fallback;
+    private readonly factory;
+    constructor(pool: sql.ConnectionPool | null, fallback: IMetadataProvider);
+    CreateProvider(): Promise<IMetadataProvider>;
+}
+/** Returns the started host, or null when this instance runs no subscriptions. */
+export declare function StartWorkQueueHost(config: WorkQueueConfig, provider: DatabaseProviderBase, providerSource: WorkQueueProviderSource, dependencies?: WorkQueueHostStartDependencies): Promise<StartableWorkQueueHost | null>;
+export {};
+//# sourceMappingURL=WorkQueueHostService.d.ts.map

package/dist/services/WorkQueueHostService.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"WorkQueueHostService.d.ts","sourceRoot":"","sources":["../../src/services/WorkQueueHostService.ts"],"names":[],"mappings":"AAMA,OAAO,GAAG,MAAM,OAAO,CAAC;AAExB,OAAO,KAAK,EAAE,oBAAoB,EAAE,iBAAiB,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AAE9F,OAAO,EAAgB,eAAe,EAAiB,MAAM,mCAAmC,CAAC;AACjG,OAAO,KAAK,EAAE,mBAAmB,EAAE,uBAAuB,EAAE,MAAM,mCAAmC,CAAC;AAEtG,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAE5D,eAAO,MAAM,sBAAsB,+BAA+B,CAAC;AAKnE,KAAK,oBAAoB,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;AAE/D,MAAM,WAAW,sBAAsB;IACnC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC1B;AAED,mFAAmF;AACnF,MAAM,WAAW,8BAA8B;IAC3C,GAAG,EAAE,oBAAoB,CAAC;IAC1B,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,QAAQ,GAAG,SAAS,CAAC;IACrD,eAAe,CAAC,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,oBAAoB,GAAG,OAAO,CAAC,eAAe,CAAC,CAAC;IAC1F,UAAU,CAAC,MAAM,EAAE,mBAAmB,EAAE,MAAM,EAAE,eAAe,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,oBAAoB,EAAE,cAAc,EAAE,uBAAuB,GAAG,sBAAsB,CAAC;CACrL;AAED,eAAO,MAAM,0CAA0C,EAAE,8BAUxD,CAAC;AAsBF,wBAAgB,4BAA4B,CAAC,GAAG,EAAE,oBAAoB,GAAG,OAAO,CAE/E;AAED;;;GAGG;AACH,wBAAgB,yBAAyB,CAAC,GAAG,GAAE,oBAAkC,GAAG,MAAM,CAGzF;AAED,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,eAAe,EAAE,UAAU,EAAE,MAAM,GAAG,mBAAmB,CAUzG;AAED,oGAAoG;AACpG,qBAAa,+BAAgC,YAAW,uBAAuB;IAG9B,OAAO,CAAC,QAAQ,CAAC,QAAQ;IAFtE,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAkC;gBAE9C,IAAI,EAAE,GAAG,CAAC,cAAc,GAAG,IAAI,EAAmB,QAAQ,EAAE,iBAAiB;IAIlF,cAAc,IAAI,OAAO,CAAC,iBAAiB,CAAC;CAGtD;AAED,kFAAkF;AAClF,wBAAsB,kBAAkB,CACpC,MAAM,EAAE,eAAe,EACvB,QAAQ,EAAE,oBAAoB,EAC9B,cAAc,EAAE,uBAAuB,EACvC,YAAY,GAAE,8BAA2E,GAC1F,OAAO,CAAC,sBAAsB,GAAG,IAAI,CAAC,CAkBxC"}

package/dist/services/WorkQueueHostService.js

@@ -0,0 +1,97 @@
+/**
+ * @fileoverview Starts the durable work-queue host inside MJServer when `workQueue.enabled` is set.
+ * @module MJServer/services
+ */
+import { randomBytes } from 'node:crypto';
+import { hostname } from 'node:os';
+import { LogError, LogStatus } from '@memberjunction/core';
+import { UserCache } from '@memberjunction/generic-database-provider';
+import { MJWorkLogger, WorkQueueEngine, WorkQueueHost } from '@memberjunction/work-queue-engine';
+import { TaskGraphProviderFactory } from './TaskGraphProviderFactory.js';
+export const WORK_QUEUE_DISABLE_ENV = 'MJ_DISABLE_WORK_QUEUE_HOST';
+/** Matches the width of WorkQueueDelivery.LeaseOwner. */
+const MAX_INSTANCE_ID_LENGTH = 200;
+export const DEFAULT_WORK_QUEUE_HOST_START_DEPENDENCIES = {
+    Env: process.env,
+    FindUserByEmail: email => UserCache.Users.find(user => user.Email?.trim().toLowerCase() === email.trim().toLowerCase()),
+    ConfigureEngine: async (user, provider) => {
+        await WorkQueueEngine.Instance.Config(false, user, provider);
+        await ReportTopologyIssues(WorkQueueEngine.Instance);
+        return WorkQueueEngine.Instance;
+    },
+    CreateHost: (config, engine, user, provider, providerSource) => new WorkQueueHost(config, engine, user, provider, new MJWorkLogger(), { ProviderSource: providerSource }),
+};
+/**
+ * Topology rows, capability gating, driver bindings and database prerequisites (03 §11) — including SQL Server's
+ * READ_COMMITTED_SNAPSHOT requirement (03 §7). Problems are logged, never thrown: the planner still gates each
+ * subscription, and an operator can read the same list from WorkQueue.ValidateBindings.
+ */
+async function ReportTopologyIssues(engine) {
+    try {
+        for (const issue of await engine.ValidateTopology()) {
+            const line = `[WorkQueue] ${issue.Severity}: ${issue.Subject} — ${issue.Message}`;
+            if (issue.Severity === 'Error') {
+                LogError(line);
+            }
+            else {
+                LogStatus(line);
+            }
+        }
+    }
+    catch (error) {
+        LogError(`[WorkQueue] Topology validation failed: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+export function IsWorkQueueHostDisabledByEnv(env) {
+    return env[WORK_QUEUE_DISABLE_ENV] === '1';
+}
+/**
+ * Host and pid for humans reading logs; the random suffix for uniqueness — containers routinely share pid 1 and
+ * HOSTNAME is not always exported. A restart is a new instance, so a dead process's leases simply expire.
+ */
+export function CreateWorkQueueInstanceID(env = process.env) {
+    const host = env.HOSTNAME ?? hostname();
+    return `${host}-${process.pid}-${randomBytes(4).toString('hex')}`.slice(0, MAX_INSTANCE_ID_LENGTH);
+}
+export function BuildWorkQueueHostConfig(config, instanceID) {
+    return {
+        InstanceID: instanceID,
+        Subscriptions: config.subscriptions.map(entry => ({ Name: entry.name, Concurrency: entry.concurrency })),
+        IdlePollMinMs: config.idlePollMinMs,
+        IdlePollMaxMs: config.idlePollMaxMs,
+        ShutdownDrainMs: config.shutdownDrainMs,
+        SweeperIntervalMs: config.sweeperEnabled ? config.sweeperIntervalMs : 0,
+        ReconcileIntervalMs: config.reconcileIntervalMs,
+    };
+}
+/** A fresh SQL Server provider per delivery over the shared pool; the server provider otherwise. */
+export class MJServerWorkQueueProviderSource {
+    constructor(pool, fallback) {
+        this.fallback = fallback;
+        this.factory = pool ? new TaskGraphProviderFactory(pool) : null;
+    }
+    CreateProvider() {
+        return this.factory ? this.factory.CreateProvider() : Promise.resolve(this.fallback);
+    }
+}
+/** Returns the started host, or null when this instance runs no subscriptions. */
+export async function StartWorkQueueHost(config, provider, providerSource, dependencies = DEFAULT_WORK_QUEUE_HOST_START_DEPENDENCIES) {
+    if (!config.enabled) {
+        return null;
+    }
+    if (IsWorkQueueHostDisabledByEnv(dependencies.Env)) {
+        LogStatus(`[WorkQueue] Host disabled by ${WORK_QUEUE_DISABLE_ENV}=1 — this process publishes but runs no subscriptions.`);
+        return null;
+    }
+    const user = dependencies.FindUserByEmail(config.systemUserEmail);
+    if (!user) {
+        throw new Error(`[WorkQueue] System user not found with email: ${config.systemUserEmail} — set workQueue.systemUserEmail in mj.config.cjs`);
+    }
+    const engine = await dependencies.ConfigureEngine(user, provider);
+    const hostConfig = BuildWorkQueueHostConfig(config, CreateWorkQueueInstanceID(dependencies.Env));
+    const host = dependencies.CreateHost(hostConfig, engine, user, provider, providerSource);
+    await host.Start();
+    LogStatus(`🔄 Work Queue host ${hostConfig.InstanceID}: ${hostConfig.Subscriptions.map(s => `${s.Name}×${s.Concurrency}`).join(', ')}`);
+    return host;
+}
+//# sourceMappingURL=WorkQueueHostService.js.map

package/dist/services/WorkQueueHostService.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"WorkQueueHostService.js","sourceRoot":"","sources":["../../src/services/WorkQueueHostService.ts"],"names":[],"mappings":"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"}

package/dist/services/workQueueConfig.d.ts

@@ -0,0 +1,103 @@
+/**
+ * @fileoverview The `workQueue` configuration section. Kept out of config.ts so it can be tested without
+ * config.ts's module-load database validation.
+ * @module MJServer/services
+ */
+import { z } from 'zod';
+export declare const WorkQueueSubscriptionEntrySchema: z.ZodObject<{
+    /** A subscription name, or '*' for every MJWorker subscription. */
+    name: z.ZodString;
+    /** Deliveries this instance processes concurrently for the subscription. */
+    concurrency: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+}, "strip", z.ZodTypeAny, {
+    name?: string;
+    concurrency?: number;
+}, {
+    name?: string;
+    concurrency?: number;
+}>;
+/**
+ * Durable work-queue host. When enabled, this process runs its share of MJWorker subscriptions. Every claim is atomic
+ * against shared state, so any number of instances may enable it against one database.
+ */
+export declare const WorkQueueSchema: z.ZodEffects<z.ZodObject<{
+    enabled: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+    systemUserEmail: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+    subscriptions: z.ZodDefault<z.ZodOptional<z.ZodArray<z.ZodObject<{
+        /** A subscription name, or '*' for every MJWorker subscription. */
+        name: z.ZodString;
+        /** Deliveries this instance processes concurrently for the subscription. */
+        concurrency: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+    }, "strip", z.ZodTypeAny, {
+        name?: string;
+        concurrency?: number;
+    }, {
+        name?: string;
+        concurrency?: number;
+    }>, "many">>>;
+    idlePollMinMs: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+    idlePollMaxMs: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+    shutdownDrainMs: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+    sweeperEnabled: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+    sweeperIntervalMs: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+    reconcileIntervalMs: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+}, "strip", z.ZodTypeAny, {
+    enabled?: boolean;
+    systemUserEmail?: string;
+    subscriptions?: {
+        name?: string;
+        concurrency?: number;
+    }[];
+    idlePollMinMs?: number;
+    idlePollMaxMs?: number;
+    shutdownDrainMs?: number;
+    sweeperEnabled?: boolean;
+    sweeperIntervalMs?: number;
+    reconcileIntervalMs?: number;
+}, {
+    enabled?: boolean;
+    systemUserEmail?: string;
+    subscriptions?: {
+        name?: string;
+        concurrency?: number;
+    }[];
+    idlePollMinMs?: number;
+    idlePollMaxMs?: number;
+    shutdownDrainMs?: number;
+    sweeperEnabled?: boolean;
+    sweeperIntervalMs?: number;
+    reconcileIntervalMs?: number;
+}>, {
+    enabled?: boolean;
+    systemUserEmail?: string;
+    subscriptions?: {
+        name?: string;
+        concurrency?: number;
+    }[];
+    idlePollMinMs?: number;
+    idlePollMaxMs?: number;
+    shutdownDrainMs?: number;
+    sweeperEnabled?: boolean;
+    sweeperIntervalMs?: number;
+    reconcileIntervalMs?: number;
+}, {
+    enabled?: boolean;
+    systemUserEmail?: string;
+    subscriptions?: {
+        name?: string;
+        concurrency?: number;
+    }[];
+    idlePollMinMs?: number;
+    idlePollMaxMs?: number;
+    shutdownDrainMs?: number;
+    sweeperEnabled?: boolean;
+    sweeperIntervalMs?: number;
+    reconcileIntervalMs?: number;
+}>;
+export type WorkQueueConfig = z.infer<typeof WorkQueueSchema>;
+/**
+ * The merge base for mj.config.cjs. Like scheduledJobs and integrationSyncWorker, the EFFECTIVE default system user
+ * is the placeholder: set workQueue.systemUserEmail explicitly, or StartWorkQueueHost fails fast and says so.
+ */
+export declare const DEFAULT_WORK_QUEUE_CONFIG: WorkQueueConfig;
+//# sourceMappingURL=workQueueConfig.d.ts.map

package/dist/services/workQueueConfig.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"workQueueConfig.d.ts","sourceRoot":"","sources":["../../src/services/workQueueConfig.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,eAAO,MAAM,gCAAgC;IAC3C,mEAAmE;;IAEnE,4EAA4E;;;;;;;;EAE5E,CAAC;AAEH;;;GAGG;AACH,eAAO,MAAM,eAAe;;;;QAV1B,mEAAmE;;QAEnE,4EAA4E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAuB1E,CAAC;AAEL,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,CAAC;AAE9D;;;GAGG;AACH,eAAO,MAAM,yBAAyB,EAAE,eAUvC,CAAC"}

package/dist/services/workQueueConfig.js

@@ -0,0 +1,48 @@
+/**
+ * @fileoverview The `workQueue` configuration section. Kept out of config.ts so it can be tested without
+ * config.ts's module-load database validation.
+ * @module MJServer/services
+ */
+import { z } from 'zod';
+export const WorkQueueSubscriptionEntrySchema = z.object({
+    /** A subscription name, or '*' for every MJWorker subscription. */
+    name: z.string().min(1),
+    /** Deliveries this instance processes concurrently for the subscription. */
+    concurrency: z.number().int().positive().optional().default(4),
+});
+/**
+ * Durable work-queue host. When enabled, this process runs its share of MJWorker subscriptions. Every claim is atomic
+ * against shared state, so any number of instances may enable it against one database.
+ */
+export const WorkQueueSchema = z
+    .object({
+    enabled: z.boolean().optional().default(false),
+    systemUserEmail: z.string().optional().default('system@memberjunction.org'),
+    subscriptions: z.array(WorkQueueSubscriptionEntrySchema).optional().default([{ name: '*', concurrency: 4 }]),
+    idlePollMinMs: z.number().int().positive().optional().default(250),
+    idlePollMaxMs: z.number().int().positive().optional().default(5000),
+    shutdownDrainMs: z.number().int().nonnegative().optional().default(8000),
+    sweeperEnabled: z.boolean().optional().default(true),
+    sweeperIntervalMs: z.number().int().positive().optional().default(60000),
+    reconcileIntervalMs: z.number().int().nonnegative().optional().default(30000),
+})
+    .refine(config => config.idlePollMaxMs >= config.idlePollMinMs, {
+    message: 'workQueue.idlePollMaxMs must be >= workQueue.idlePollMinMs',
+    path: ['idlePollMaxMs'],
+});
+/**
+ * The merge base for mj.config.cjs. Like scheduledJobs and integrationSyncWorker, the EFFECTIVE default system user
+ * is the placeholder: set workQueue.systemUserEmail explicitly, or StartWorkQueueHost fails fast and says so.
+ */
+export const DEFAULT_WORK_QUEUE_CONFIG = {
+    enabled: false,
+    systemUserEmail: 'not.set@nowhere.com',
+    subscriptions: [{ name: '*', concurrency: 4 }],
+    idlePollMinMs: 250,
+    idlePollMaxMs: 5000,
+    shutdownDrainMs: 8000,
+    sweeperEnabled: true,
+    sweeperIntervalMs: 60000,
+    reconcileIntervalMs: 30000,
+};
+//# sourceMappingURL=workQueueConfig.js.map

package/dist/services/workQueueConfig.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"workQueueConfig.js","sourceRoot":"","sources":["../../src/services/workQueueConfig.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,MAAM,CAAC,MAAM,gCAAgC,GAAG,CAAC,CAAC,MAAM,CAAC;IACvD,mEAAmE;IACnE,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IACvB,4EAA4E;IAC5E,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,EAAE,CAAC,OAAO,CAAC,CAAC,CAAC;CAC/D,CAAC,CAAC;AAEH;;;GAGG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG,CAAC;KAC7B,MAAM,CAAC;IACN,OAAO,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,QAAQ,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC;IAC9C,eAAe,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,OAAO,CAAC,2BAA2B,CAAC;IAC3E,aAAa,EAAE,CAAC,CAAC,KAAK,CAAC,gCAAgC,CAAC,CAAC,QAAQ,EAAE,CAAC,OAAO,CAAC,CAAC,EAAE,IAAI,EAAE,GAAG,EAAE,WAAW,EAAE,CAAC,EAAE,CAAC,CAAC;IAC5G,aAAa,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC;IAClE,aAAa,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC;IACnE,eAAe,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,WAAW,EAAE,CAAC,QAAQ,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC;IACxE,cAAc,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,QAAQ,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC;IACpD,iBAAiB,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC;IACxE,mBAAmB,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,WAAW,EAAE,CAAC,QAAQ,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC;CAC9E,CAAC;KACD,MAAM,CAAC,MAAM,CAAC,EAAE,CAAC,MAAM,CAAC,aAAa,IAAI,MAAM,CAAC,aAAa,EAAE;IAC9D,OAAO,EAAE,4DAA4D;IACrE,IAAI,EAAE,CAAC,eAAe,CAAC;CACxB,CAAC,CAAC;AAIL;;;GAGG;AACH,MAAM,CAAC,MAAM,yBAAyB,GAAoB;IACxD,OAAO,EAAE,KAAK;IACd,eAAe,EAAE,qBAAqB;IACtC,aAAa,EAAE,CAAC,EAAE,IAAI,EAAE,GAAG,EAAE,WAAW,EAAE,CAAC,EAAE,CAAC;IAC9C,aAAa,EAAE,GAAG;IAClB,aAAa,EAAE,IAAI;IACnB,eAAe,EAAE,IAAI;IACrB,cAAc,EAAE,IAAI;IACpB,iBAAiB,EAAE,KAAK;IACxB,mBAAmB,EAAE,KAAK;CAC3B,CAAC"}

package/dist/sharedCache.d.ts

@@ -0,0 +1,105 @@
+import type { CacheChangedEvent, LocalCacheManagerConfig, ProviderBase } from '@memberjunction/core';
+import type { CacheSettingsConfig } from './config.js';
+import { RedisLocalStorageProvider } from '@memberjunction/redis-provider';
+import type { CachePublishMode } from '@memberjunction/redis-provider';
+/**
+ * What an MJAPI process publishes, per category.
+ *
+ * - RunView slots carry their rows: engines on other servers apply them directly.
+ * - Writes without a category (the provider's metadata snapshot, ~2 MB compressed) publish a
+ *   notice only: other servers re-check their metadata against the database and adopt the shared
+ *   snapshot, so the value never needs to travel.
+ * - Everything else (dataset slots, query slots, registry) has no subscriber and publishes nothing.
+ * Category clears are always published.
+ */
+export declare const MJAPI_PUBLISH_MODES: Readonly<Record<string, CachePublishMode>>;
+/** Options for {@link CreateSharedCacheProvider}. */
+export interface SharedCacheProviderOptions {
+    Url: string;
+    KeyPrefix: string;
+    DefaultTTLSeconds?: number;
+    EnableLogging: boolean;
+}
+/**
+ * Expiry for the shared Redis cache: `REDIS_TTL_SECONDS` when it holds a non-negative integer,
+ * otherwise `cacheSettings.sharedCacheTTLSeconds`, otherwise `undefined` (the provider's default).
+ */
+export declare function ResolveSharedCacheTTLSeconds(configured: number | undefined, env?: NodeJS.ProcessEnv): number | undefined;
+/**
+ * The shared cache the environment asks for (`REDIS_URL`, `REDIS_KEY_PREFIX`, `REDIS_TTL_SECONDS`),
+ * or null. Built before the database provider so metadata and startup engines use it from the
+ * first read.
+ */
+export declare function CreateSharedCacheFromEnvironment(settings: CacheSettingsConfig | undefined, env?: NodeJS.ProcessEnv): RedisLocalStorageProvider | null;
+/**
+ * The warm-up lease MJAPI hands to `StartupManager`, in milliseconds, from
+ * `cacheSettings.startupWarmupLeaseSeconds` (default 30).
+ */
+export declare function WarmupLeaseMsFromSettings(settings: CacheSettingsConfig | undefined): number;
+/** `LocalCacheManager` settings from `cacheSettings` in mj.config.cjs. */
+export declare function CacheManagerConfigFromSettings(settings: CacheSettingsConfig | undefined): Partial<LocalCacheManagerConfig>;
+/**
+ * Starts the periodic engine-vs-database sweep (plan Phase 3.1) at
+ * `cacheSettings.engineSweepIntervalSeconds` (default 300; 0 leaves it off).
+ * @returns The interval in milliseconds, 0 when disabled.
+ */
+export declare function StartEngineSweeper(settings: CacheSettingsConfig | undefined): number;
+/**
+ * Starts the periodic metadata-vs-database sweep at `cacheSettings.metadataSweepIntervalSeconds`
+ * (default 300; 0 leaves it off).
+ *
+ * The sweep asks the database **nothing** unless one of the entities the metadata is built from
+ * declares `TrustServerCacheCompletely = false` — see `ProviderBase.SweepMetadataAgainstDatabase`.
+ * On a stock installation no metadata entity declares it, so the timer ticks and costs nothing. It
+ * exists for installations that write metadata tables directly, where no event is ever raised and
+ * nothing else would notice.
+ *
+ * One process per interval does the work, via a shared lease: a process that refreshes writes a new
+ * snapshot and publishes a notice, which the others act on, so there is no value in each of them
+ * asking the database the same question.
+ *
+ * @returns The interval in milliseconds, 0 when disabled.
+ */
+export declare function StartMetadataSweep(settings: CacheSettingsConfig | undefined, metadataProvider: () => ProviderBase | undefined): number;
+/**
+ * Starts the periodic user-cache staleness check at `cacheSettings.userCacheCheckIntervalSeconds`
+ * (default 300; 0 leaves it off). The cache refreshes on MJ writes by itself — this covers users
+ * and roles changed outside MJ.
+ * @returns The interval in milliseconds, 0 when disabled.
+ */
+export declare function StartUserCacheChecks(settings: CacheSettingsConfig | undefined): number;
+/** Builds the Redis provider MJAPI uses as its shared cache. Pub/sub starts with {@link WireSharedCacheEvents}. */
+export declare function CreateSharedCacheProvider(options: SharedCacheProviderOptions): RedisLocalStorageProvider;
+/**
+ * Subscribes to other servers' cache events and routes them. Called before the database provider
+ * exists (so engines hear peers while they load); `metadataProvider` is resolved per event.
+ * 1. a metadata-snapshot notice → a metadata staleness check on this process's provider, and
+ *    nothing further (a consumed notice returns here);
+ * 2. every other event → `LocalCacheManager.DispatchCacheChange` (engines, the user cache, and
+ *    RunView callbacks);
+ * 3. RunView slot changes → an entity-level invalidation to connected browsers.
+ */
+export declare function WireSharedCacheEvents(redis: RedisLocalStorageProvider, metadataProvider: () => ProviderBase | undefined): Promise<void>;
+/** One incoming event, routed as described on {@link WireSharedCacheEvents}. */
+export declare function RouteSharedCacheEvent(event: CacheChangedEvent, metadataProvider: ProviderBase | undefined): void;
+/**
+ * Replicate push-status updates across server instances over Redis (MJ #4222).
+ *
+ * Outbound: every locally-published update is forwarded on a shared channel. Inbound: a message
+ * from another instance is republished onto THIS instance's local topic, where the normal
+ * subscription filter decides who receives it — so the identity gate (`ownerUserId` vs. the
+ * connection's authenticated user) still applies to a replicated message exactly as it does to a
+ * local one. The replica has no say in who sees what.
+ *
+ * Republishing goes straight to `PubSubManager`, never back through `publishStatusUpdate`, so an
+ * inbound message cannot be re-broadcast and loop. `SourceServerId` guards the remaining case: a
+ * publisher also receives its own message from Redis.
+ *
+ * The channel rides the same connection and subscriber as cache invalidation, and is namespaced
+ * with the provider's key prefix — so replicas configured with different `REDIS_KEY_PREFIX`
+ * values stop replicating to each other, exactly as their caches do.
+ *
+ * @param redis The shared cache provider, already built by {@link CreateSharedCacheFromEnvironment}.
+ */
+export declare function WirePushStatusFanOut(redis: RedisLocalStorageProvider): Promise<void>;
+//# sourceMappingURL=sharedCache.d.ts.map

package/dist/sharedCache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sharedCache.d.ts","sourceRoot":"","sources":["../src/sharedCache.ts"],"names":[],"mappings":"AAYA,OAAO,KAAK,EAAE,iBAAiB,EAAE,uBAAuB,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AACrG,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AACvD,OAAO,EAAE,yBAAyB,EAAE,MAAM,gCAAgC,CAAC;AAC3E,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,gCAAgC,CAAC;AAOvE;;;;;;;;;GASG;AACH,eAAO,MAAM,mBAAmB,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAG1E,CAAC;AAEF,qDAAqD;AACrD,MAAM,WAAW,0BAA0B;IACvC,GAAG,EAAE,MAAM,CAAC;IACZ,SAAS,EAAE,MAAM,CAAC;IAClB,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,aAAa,EAAE,OAAO,CAAC;CAC1B;AAED;;;GAGG;AACH,wBAAgB,4BAA4B,CAAC,UAAU,EAAE,MAAM,GAAG,SAAS,EAAE,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,MAAM,GAAG,SAAS,CAUrI;AAED;;;;GAIG;AACH,wBAAgB,gCAAgC,CAAC,QAAQ,EAAE,mBAAmB,GAAG,SAAS,EAAE,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,yBAAyB,GAAG,IAAI,CAUlK;AAED;;;GAGG;AACH,wBAAgB,yBAAyB,CAAC,QAAQ,EAAE,mBAAmB,GAAG,SAAS,GAAG,MAAM,CAE3F;AAED,0EAA0E;AAC1E,wBAAgB,8BAA8B,CAAC,QAAQ,EAAE,mBAAmB,GAAG,SAAS,GAAG,OAAO,CAAC,uBAAuB,CAAC,CAQ1H;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,mBAAmB,GAAG,SAAS,GAAG,MAAM,CAIpF;AAKD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,mBAAmB,GAAG,SAAS,EAAE,gBAAgB,EAAE,MAAM,YAAY,GAAG,SAAS,GAAG,MAAM,CAgBtI;AA0BD;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,mBAAmB,GAAG,SAAS,GAAG,MAAM,CAItF;AAED,mHAAmH;AACnH,wBAAgB,yBAAyB,CAAC,OAAO,EAAE,0BAA0B,GAAG,yBAAyB,CAWxG;AAED;;;;;;;;GAQG;AACH,wBAAsB,qBAAqB,CAAC,KAAK,EAAE,yBAAyB,EAAE,gBAAgB,EAAE,MAAM,YAAY,GAAG,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC,CAG7I;AAED,gFAAgF;AAChF,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,YAAY,GAAG,SAAS,GAAG,IAAI,CAShH;AA2BD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAsB,oBAAoB,CAAC,KAAK,EAAE,yBAAyB,GAAG,OAAO,CAAC,IAAI,CAAC,CAoC1F"}