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

package/src/resolvers/meetings/meetingQueries.ts

@@ -0,0 +1,172 @@
+import {
+  IMetadataProvider,
+  LogError,
+  RunView,
+  UserInfo,
+} from '@memberjunction/core';
+import { EscapeSQLString, UUIDsEqual } from '@memberjunction/global';
+import type {
+  MJMeetingEntity,
+  MJMeetingParticipantEntity,
+  MJPhoneNumberEntity,
+} from '@memberjunction/core-entities';
+import {
+  MeetingType,
+  MeetingParticipantType,
+  DialInPhoneNumberType,
+} from './meetingTypes.js';
+import {
+  LoadParticipants,
+  MapMeetingToType,
+} from './meetingHelpers.js';
+
+export async function ExecuteMyMeetings(
+  provider: IMetadataProvider,
+  user: UserInfo,
+  status?: string,
+): Promise<MeetingType[]> {
+  try {
+    const rv = provider ? RunView.FromMetadataProvider(provider) : new RunView();
+    const escapedUserID = EscapeSQLString(user.ID);
+
+    // 1. Find participant rows for this user
+    const participantRows = await rv.RunView<MJMeetingParticipantEntity>(
+      {
+        EntityName: 'MJ: Meeting Participants',
+        ExtraFilter: `UserID = '${escapedUserID}'`,
+        ResultType: 'entity_object',
+      },
+      user,
+    );
+
+    const participantMeetingIDs = new Set<string>();
+    if (participantRows.Success && participantRows.Results) {
+      for (const p of participantRows.Results) {
+        if (p.MeetingID) {
+          participantMeetingIDs.add(p.MeetingID);
+        }
+      }
+    }
+
+    // 2. Query meetings where user is host OR in participantMeetingIDs
+    let filter = `HostUserID = '${escapedUserID}'`;
+    if (participantMeetingIDs.size > 0) {
+      const idList = Array.from(participantMeetingIDs)
+        .map((id) => `'${EscapeSQLString(id)}'`)
+        .join(', ');
+      filter = `(HostUserID = '${escapedUserID}' OR ID IN (${idList}))`;
+    }
+
+    if (status && status.trim()) {
+      const escapedStatus = EscapeSQLString(status.trim());
+      filter = `${filter} AND Status = '${escapedStatus}'`;
+    }
+
+    const meetingsResult = await rv.RunView<MJMeetingEntity>(
+      {
+        EntityName: 'MJ: Meetings',
+        ExtraFilter: filter,
+        OrderBy: 'ScheduledStartAt DESC, __mj_CreatedAt DESC',
+        ResultType: 'entity_object',
+      },
+      user,
+    );
+
+    if (!meetingsResult.Success || !meetingsResult.Results) {
+      return [];
+    }
+
+    const output: MeetingType[] = [];
+    for (const m of meetingsResult.Results) {
+      const participants = await LoadParticipants(m.ID, user, provider);
+      output.push(MapMeetingToType(m, participants));
+    }
+    return output;
+  } catch (error) {
+    LogError(`[MeetingResolver] MyMeetings failed: ${error instanceof Error ? error.message : String(error)}`);
+    return [];
+  }
+}
+
+export async function ExecuteMeeting(
+  provider: IMetadataProvider,
+  user: UserInfo,
+  id: string,
+): Promise<MeetingType | null> {
+  try {
+    const rv = provider ? RunView.FromMetadataProvider(provider) : new RunView();
+    const escapedID = EscapeSQLString(id.trim());
+
+    const result = await rv.RunView<MJMeetingEntity>(
+      {
+        EntityName: 'MJ: Meetings',
+        ExtraFilter: `ID = '${escapedID}'`,
+        ResultType: 'entity_object',
+      },
+      user,
+    );
+
+    if (!result.Success || !result.Results || result.Results.length === 0) {
+      return null;
+    }
+
+    const meeting = result.Results[0];
+    const participants = await LoadParticipants(meeting.ID, user, provider);
+
+    // Verify authorization: caller must be host or participant
+    const isHost = UUIDsEqual(meeting.HostUserID, user.ID);
+    const isParticipant = participants.some((p) => p.UserID && UUIDsEqual(p.UserID, user.ID));
+    if (!isHost && !isParticipant) {
+      return null;
+    }
+
+    return MapMeetingToType(meeting, participants);
+  } catch (error) {
+    LogError(`[MeetingResolver] Meeting query failed: ${error instanceof Error ? error.message : String(error)}`);
+    return null;
+  }
+}
+
+export async function ExecuteMeetingParticipants(
+  provider: IMetadataProvider,
+  user: UserInfo,
+  meetingID: string,
+): Promise<MeetingParticipantType[]> {
+  try {
+    return await LoadParticipants(meetingID.trim(), user, provider);
+  } catch (error) {
+    LogError(`[MeetingResolver] MeetingParticipants failed: ${error instanceof Error ? error.message : String(error)}`);
+    return [];
+  }
+}
+
+export async function ExecuteAvailableDialInPhoneNumbers(
+  provider: IMetadataProvider,
+  user: UserInfo,
+): Promise<DialInPhoneNumberType[]> {
+  try {
+    const rv = provider ? RunView.FromMetadataProvider(provider) : new RunView();
+
+    const result = await rv.RunView<MJPhoneNumberEntity>(
+      {
+        EntityName: 'MJ: Phone Numbers',
+        ExtraFilter: "Status = 'Active'",
+        ResultType: 'entity_object',
+      },
+      user,
+    );
+
+    if (!result.Success || !result.Results) {
+      return [];
+    }
+
+    return result.Results.map((p) => ({
+      ID: p.ID,
+      Number: p.Number,
+      Label: p.Label ?? undefined,
+    }));
+  } catch (error) {
+    LogError(`[MeetingResolver] AvailableDialInPhoneNumbers failed: ${error instanceof Error ? error.message : String(error)}`);
+    return [];
+  }
+}

package/src/resolvers/meetings/meetingTypes.ts

@@ -0,0 +1,238 @@
+import { ObjectType, InputType, Field } from 'type-graphql';
+
+@ObjectType()
+export class MeetingParticipantType {
+  @Field(() => String)
+  ID: string;
+
+  @Field(() => String)
+  MeetingID: string;
+
+  @Field(() => String, { nullable: true })
+  UserID?: string;
+
+  @Field(() => String, { nullable: true })
+  UserName?: string;
+
+  @Field(() => String, { nullable: true })
+  UserEmail?: string;
+
+  @Field(() => String, { nullable: true })
+  AgentID?: string;
+
+  @Field(() => String, { nullable: true })
+  AgentName?: string;
+
+  @Field(() => String, { nullable: true })
+  ExternalName?: string;
+
+  @Field(() => String, { nullable: true })
+  ExternalEmail?: string;
+
+  @Field(() => String, { nullable: true })
+  ExternalPhone?: string;
+
+  @Field(() => String)
+  Role: string;
+
+  @Field(() => String)
+  InviteStatus: string;
+
+  @Field(() => Date, { nullable: true })
+  JoinedAt?: Date;
+
+  @Field(() => Date, { nullable: true })
+  LeftAt?: Date;
+}
+
+@ObjectType()
+export class MeetingType {
+  @Field(() => String)
+  ID: string;
+
+  @Field(() => String)
+  Title: string;
+
+  @Field(() => String, { nullable: true })
+  Description?: string;
+
+  @Field(() => String)
+  HostUserID: string;
+
+  @Field(() => String, { nullable: true })
+  HostUserName?: string;
+
+  @Field(() => String)
+  RoomName: string;
+
+  @Field(() => String)
+  Status: string;
+
+  @Field(() => Date, { nullable: true })
+  ScheduledStartAt?: Date;
+
+  @Field(() => Date, { nullable: true })
+  ScheduledEndAt?: Date;
+
+  @Field(() => Date, { nullable: true })
+  StartedAt?: Date;
+
+  @Field(() => Date, { nullable: true })
+  EndedAt?: Date;
+
+  @Field(() => Boolean)
+  AllowPhoneDialIn: boolean;
+
+  @Field(() => String, { nullable: true })
+  DialInPhoneNumberID?: string;
+
+  @Field(() => String, { nullable: true })
+  DialInPhoneNumber?: string;
+
+  @Field(() => String, { nullable: true })
+  DialInCode?: string;
+
+  @Field(() => String)
+  RecordingPolicy: string;
+
+  @Field(() => String, { nullable: true })
+  ConversationID?: string;
+
+  @Field(() => [MeetingParticipantType], { nullable: true })
+  Participants?: MeetingParticipantType[];
+
+  @Field(() => Date)
+  CreatedAt: Date;
+
+  @Field(() => Date)
+  UpdatedAt: Date;
+}
+
+@ObjectType()
+export class MeetingResult {
+  @Field(() => Boolean)
+  Success: boolean;
+
+  @Field(() => String, { nullable: true })
+  ErrorMessage?: string;
+
+  @Field(() => MeetingType, { nullable: true })
+  Meeting?: MeetingType;
+}
+
+@ObjectType()
+export class StartMeetingResult {
+  @Field(() => Boolean)
+  Success: boolean;
+
+  @Field(() => String, { nullable: true })
+  ErrorMessage?: string;
+
+  @Field(() => MeetingType, { nullable: true })
+  Meeting?: MeetingType;
+
+  @Field(() => String, { nullable: true })
+  RoomName?: string;
+
+  @Field(() => String, { nullable: true })
+  ClientToken?: string;
+}
+
+@ObjectType()
+export class DialInPhoneNumberType {
+  @Field(() => String)
+  ID: string;
+
+  @Field(() => String)
+  Number: string;
+
+  @Field(() => String, { nullable: true })
+  Label?: string;
+}
+
+@InputType()
+export class MeetingParticipantInput {
+  @Field(() => String, { nullable: true })
+  UserID?: string;
+
+  @Field(() => String, { nullable: true })
+  AgentID?: string;
+
+  @Field(() => String, { nullable: true })
+  ExternalName?: string;
+
+  @Field(() => String, { nullable: true })
+  ExternalEmail?: string;
+
+  @Field(() => String, { nullable: true })
+  ExternalPhone?: string;
+
+  @Field(() => String, { nullable: true })
+  Role?: string;
+}
+
+@InputType()
+export class CreateMeetingInput {
+  @Field(() => String)
+  Title: string;
+
+  @Field(() => String, { nullable: true })
+  Description?: string;
+
+  @Field(() => Date, { nullable: true })
+  ScheduledStartAt?: Date;
+
+  @Field(() => Date, { nullable: true })
+  ScheduledEndAt?: Date;
+
+  @Field(() => Boolean, { nullable: true })
+  AllowPhoneDialIn?: boolean;
+
+  @Field(() => String, { nullable: true })
+  DialInPhoneNumberID?: string;
+
+  @Field(() => String, { nullable: true })
+  RecordingPolicy?: string;
+
+  @Field(() => [MeetingParticipantInput], { nullable: true })
+  Participants?: MeetingParticipantInput[];
+}
+
+@InputType()
+export class UpdateMeetingInput {
+  @Field(() => String)
+  MeetingID: string;
+
+  @Field(() => String, { nullable: true })
+  Title?: string;
+
+  @Field(() => String, { nullable: true })
+  Description?: string;
+
+  @Field(() => Date, { nullable: true })
+  ScheduledStartAt?: Date;
+
+  @Field(() => Date, { nullable: true })
+  ScheduledEndAt?: Date;
+
+  @Field(() => Boolean, { nullable: true })
+  AllowPhoneDialIn?: boolean;
+
+  @Field(() => String, { nullable: true })
+  DialInPhoneNumberID?: string;
+
+  @Field(() => String, { nullable: true })
+  RecordingPolicy?: string;
+
+  @Field(() => [MeetingParticipantInput], { nullable: true })
+  Participants?: MeetingParticipantInput[];
+}
+
+@InputType()
+export class RSVPMeetingInput {
+  @Field(() => String)
+  MeetingID: string;
+
+  @Field(() => String)
+  InviteStatus: string;
+}

package/src/rest/ViewOperationsHandler.ts

@@ -206,17 +206,20 @@ export class ViewOperationsHandler {
             params.Fields = (params.Fields as string).split(',');
         }
         
-        // Sanitize numeric values
+        // Sanitize numeric values: base-10, integral, and clamped to a sane range so a
+        // negative/garbage value can never reach the SQL layer.
         if (params.MaxRows !== undefined) {
-            params.MaxRows = typeof params.MaxRows === 'string' 
-                ? parseInt(params.MaxRows as string) 
+            const parsed = typeof params.MaxRows === 'string'
+                ? parseInt(params.MaxRows as string, 10)
                 : params.MaxRows;
+            params.MaxRows = Number.isFinite(parsed) ? Math.max(0, Math.floor(parsed as number)) : undefined;
         }
         
         if (params.StartRow !== undefined) {
-            params.StartRow = typeof params.StartRow === 'string' 
-                ? parseInt(params.StartRow as string) 
+            const parsed = typeof params.StartRow === 'string'
+                ? parseInt(params.StartRow as string, 10)
                 : params.StartRow;
+            params.StartRow = Number.isFinite(parsed) ? Math.max(0, Math.floor(parsed as number)) : undefined;
         }
         
         // Default ResultType if not provided

package/src/services/TaskGraphActionRunner.ts

@@ -35,9 +35,19 @@ export class TaskGraphActionRunner implements TaskActionRunner {
                 Filters: [],
             });
 
+            const output = this.buildOutput(result.Params);
+            const unstorable = this.findUnstorableOutput(output);
+            if (unstorable) {
+                const message =
+                    `Action "${action.Name}" returned output param "${unstorable.Name}", which cannot be stored ` +
+                    `as the step's result: ${unstorable.Reason}. Output params of a durable step must be plain data.`;
+                LogError(`[TaskGraphActionRunner] Task ${params.TaskID}: ${message}`);
+                return { Success: false, ErrorMessage: message, ActionLogID: result.LogEntry?.ID };
+            }
+
             return {
                 Success: result.Success,
-                Output: this.buildOutput(result.Params),
+                Output: output,
                 ErrorMessage: result.Success ? undefined : result.Message,
                 // The engine already wrote the log; this is the only place its id is in hand. Without
                 // carrying it out, a workflow's action step has no path back to its own execution
@@ -51,6 +61,24 @@ export class TaskGraphActionRunner implements TaskActionRunner {
         }
     }
 
+    /**
+     * The first output param that cannot be written to the Task row as JSON, or null.
+     *
+     * Checked here because this is the last place that knows the action's and the param's NAMES: the
+     * dispatcher serializes the whole Output later and, for a live object (an entity, an observable),
+     * fails with a bare "Converting circular structure to JSON" that names neither.
+     */
+    private findUnstorableOutput(output: Record<string, unknown>): { Name: string; Reason: string } | null {
+        for (const [Name, value] of Object.entries(output)) {
+            try {
+                JSON.stringify(value);
+            } catch (e) {
+                return { Name, Reason: e instanceof Error ? e.message.split('\n')[0] : String(e) };
+            }
+        }
+        return null;
+    }
+
     /**
      * Projects the action's parameters onto the flat result a workflow step is expected to produce.
      *

package/src/services/TaskGraphContinuationDeliverer.ts

@@ -46,7 +46,8 @@ export class TaskGraphContinuationDeliverer implements TaskContinuationDeliverer
     ) {}
 
     /**
-     * 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
@@ -62,8 +63,8 @@ export class TaskGraphContinuationDeliverer implements TaskContinuationDeliverer
             }
 
             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.`
@@ -73,7 +74,8 @@ export class TaskGraphContinuationDeliverer implements TaskContinuationDeliverer
 
             const detail = await provider.GetEntityObject<MJConversationDetailEntity>('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;
@@ -125,11 +127,15 @@ export class TaskGraphContinuationDeliverer implements TaskContinuationDeliverer
                 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,
@@ -149,10 +155,10 @@ export class TaskGraphContinuationDeliverer implements TaskContinuationDeliverer
         }
     }
 
-    /** The conversation a detail belongs to. */
-    private async resolveConversationID(conversationDetailID: string, provider: IMetadataProvider): Promise<string | null> {
+    /** The conversation and fork (null is Main) of the detail that started the graph; null when it cannot be loaded. */
+    private async resolveOrigin(conversationDetailID: string, provider: IMetadataProvider): Promise<{ ConversationID: string; BranchID: string | null } | null> {
         const detail = await provider.GetEntityObject<MJConversationDetailEntity>('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;
     }
 
     /**

package/src/services/WorkQueueHostService.ts

@@ -0,0 +1,129 @@
+/**
+ * @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 sql from 'mssql';
+import { LogError, LogStatus } from '@memberjunction/core';
+import type { DatabaseProviderBase, IMetadataProvider, UserInfo } from '@memberjunction/core';
+import { UserCache } from '@memberjunction/generic-database-provider';
+import { MJWorkLogger, WorkQueueEngine, WorkQueueHost } from '@memberjunction/work-queue-engine';
+import type { WorkQueueHostConfig, WorkQueueProviderSource } from '@memberjunction/work-queue-engine';
+import { TaskGraphProviderFactory } from './TaskGraphProviderFactory.js';
+import type { WorkQueueConfig } from './workQueueConfig.js';
+
+export const WORK_QUEUE_DISABLE_ENV = 'MJ_DISABLE_WORK_QUEUE_HOST';
+
+/** Matches the width of WorkQueueDelivery.LeaseOwner. */
+const MAX_INSTANCE_ID_LENGTH = 200;
+
+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 const DEFAULT_WORK_QUEUE_HOST_START_DEPENDENCIES: WorkQueueHostStartDependencies = {
+    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: WorkQueueEngine): Promise<void> {
+    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: EnvironmentVariables): boolean {
+    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: EnvironmentVariables = process.env): string {
+    const host = env.HOSTNAME ?? hostname();
+    return `${host}-${process.pid}-${randomBytes(4).toString('hex')}`.slice(0, MAX_INSTANCE_ID_LENGTH);
+}
+
+export function BuildWorkQueueHostConfig(config: WorkQueueConfig, instanceID: string): WorkQueueHostConfig {
+    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 implements WorkQueueProviderSource {
+    private readonly factory: TaskGraphProviderFactory | null;
+
+    constructor(pool: sql.ConnectionPool | null, private readonly fallback: IMetadataProvider) {
+        this.factory = pool ? new TaskGraphProviderFactory(pool) : null;
+    }
+
+    public CreateProvider(): Promise<IMetadataProvider> {
+        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: WorkQueueConfig,
+    provider: DatabaseProviderBase,
+    providerSource: WorkQueueProviderSource,
+    dependencies: WorkQueueHostStartDependencies = DEFAULT_WORK_QUEUE_HOST_START_DEPENDENCIES,
+): Promise<StartableWorkQueueHost | null> {
+    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;
+}