@platformatic/runtime 3.67.0 → 4.0.0-new-config.0

package/config.d.ts

@@ -29,7 +29,6 @@ export type PlatformaticRuntimeConfig = {
             build?: boolean;
           }
       )[];
-  entrypoint?: string;
   basePath?: string;
   autoload?: {
     path: string;
@@ -43,8 +42,11 @@ export type PlatformaticRuntimeConfig = {
           | {
               [k: string]: boolean;
             };
-        config?: string;
-        useHttp?: boolean;
+        config?:
+          | string
+          | {
+              [k: string]: unknown;
+            };
         reuseTcpPorts?: boolean;
         workers?:
           | number
@@ -218,46 +220,6 @@ export type PlatformaticRuntimeConfig = {
     };
     [k: string]: unknown;
   };
-  server?: {
-    hostname?: string;
-    port?: number | string;
-    /**
-     * Configures how entrypoint server worker ports are assigned. When set to shared, all workers listen on the same port. When set to perWorkerIncrement, each worker will use its own port, starting from port (worker 0).
-     */
-    portAssignment?: "shared" | "perWorkerIncrement";
-    /**
-     * The maximum length of the queue of pending connections
-     */
-    backlog?: number;
-    http2?: boolean;
-    https?: {
-      allowHTTP1?: boolean;
-      key:
-        | string
-        | {
-            path?: string;
-          }
-        | (
-            | string
-            | {
-                path?: string;
-              }
-          )[];
-      cert:
-        | string
-        | {
-            path?: string;
-          }
-        | (
-            | string
-            | {
-                path?: string;
-              }
-          )[];
-      requestCert?: boolean;
-      rejectUnauthorized?: boolean;
-    };
-  };
   reuseTcpPorts?: boolean;
   startTimeout?: number;
   restartOnError?: boolean | number;

package/index.d.ts

@@ -37,6 +37,8 @@ export interface LoopbackMessagingOptions {
 }
 
 export namespace errors {
+  export const AddressInUseError: (port: number, firstApplication: string, secondApplication: string) => FastifyError
+  export const WorkerAddressInUseError: (port: number, application: string) => FastifyError
   export const RuntimeExitedError: () => FastifyError
   export const UnknownRuntimeAPICommandError: (command: string) => FastifyError
   export const ApplicationNotFoundError: (id: string) => FastifyError
@@ -46,8 +48,6 @@ export namespace errors {
   export const RuntimeNotStartedError: () => FastifyError
   export const ConfigPathMustBeStringError: () => FastifyError
   export const NoConfigFileFoundError: (id: string) => FastifyError
-  export const InvalidEntrypointError: (entrypoint: string) => FastifyError
-  export const MissingEntrypointError: () => FastifyError
   export const MissingDependencyError: (dependency: string) => FastifyError
   export const InspectAndInspectBrkError: () => FastifyError
   export const InspectorPortError: () => FastifyError
@@ -89,6 +89,7 @@ export namespace symbols {
   export const kLastWorkerScalerELU: unique symbol
   export const kWorkerStatus: unique symbol
   export const kWorkerHealthSignals: unique symbol
+  export const kWorkerUrl: unique symbol
   export const kStderrMarker: string
   export const kWorkersBroadcast: unique symbol
 }
@@ -119,14 +120,13 @@ export interface ApplicationDetails {
   dependencies?: string[]
   version?: string
   localUrl?: string
-  entrypoint?: boolean
   sourceMaps?: boolean
   workers?: number
   url?: string | null
+  urls?: string[]
 }
 
 export interface ApplicationsTopology {
-  entrypoint: string
   production: boolean
   applications: ApplicationDetails[]
 }
@@ -196,8 +196,8 @@ export interface RuntimeMetadata {
   projectDir: string
   packageName: string | null
   packageVersion: string | null
-  url: string | null
   platformaticVersion: string
+  urls: Record<string, string>
 }
 
 export interface WorkerLifecycleEvent {
@@ -234,9 +234,7 @@ export interface HealthMetricsEvent extends WorkerLifecycleEvent {
   healthSignals: RuntimeHealthSignal[]
 }
 
-export declare class ManagementClient {
-  constructor (allowedOperations?: string[])
-
+export interface ManagementClient {
   getRuntimeStatus (): Promise<string>
   getRuntimeMetadata (): Promise<RuntimeMetadata>
   getRuntimeConfig (): Promise<Record<string, unknown>>
@@ -257,7 +255,7 @@ export declare class ManagementClient {
   startApplication (id: string): Promise<void>
   stopApplication (id: string): Promise<void>
   restartApplication (id: string): Promise<void>
-  restart (applications?: string[]): Promise<string>
+  restart (applications?: string[]): Promise<void>
   addApplications (applications: unknown[], start?: boolean): Promise<ApplicationDetails[]>
   removeApplications (ids: string[]): Promise<ApplicationDetails[]>
   inject (id: string, injectParams: InjectParams): Promise<InjectResponse>
@@ -369,12 +367,11 @@ export type RuntimeExtension = (
 
 export declare class Runtime extends EventEmitter {
   init (): Promise<void>
-  start (silent?: boolean): Promise<string | undefined>
+  start (silent?: boolean): Promise<Record<string, string>>
   stop (silent?: boolean): Promise<void>
   close (silent?: boolean): Promise<void>
-  restart (applications?: string[]): Promise<string | undefined>
+  restart (applications?: string[]): Promise<void>
   inject (id: string, injectParams: InjectParams): Promise<InjectResponse>
-  getUrl (): string | undefined
   getRuntimeStatus (): string
   getRuntimeMetadata (): Promise<RuntimeMetadata>
   getRuntimeEnv (): Record<string, string>
@@ -385,6 +382,7 @@ export declare class Runtime extends EventEmitter {
   getRuntimeConfig (includeMeta: true): RuntimeConfiguration
   getRuntimeConfig (includeMeta?: boolean): Record<string, unknown>
   getApplicationsIds (): string[]
+  getUrls (applicationId?: string): Record<string, string>
   /**
    * Returns topology for every configured application.
    * When `allowUnloaded` is `true`, applications without running workers are

package/index.js

@@ -1,4 +1,4 @@
-import { resolve, validationOptions } from '@platformatic/basic'
+import { importCapabilityPackage, resolve, validationOptions } from '@platformatic/basic'
 import {
   abstractLogger,
   ensureLoggableError,
@@ -8,9 +8,17 @@ import {
   loadConfigurationModule,
   loadConfiguration as utilsLoadConfiguration
 } from '@platformatic/foundation'
+import {
+  isConfigurationFileName,
+  findDecidingFile,
+  loadConfiguration as loadV4Configuration,
+  validateCapabilityConfiguration
+} from '@platformatic/foundation/lib/v4/index.js'
 import closeWithGrace from 'close-with-grace'
+import { stat } from 'node:fs/promises'
 import inspector from 'node:inspector'
-import { transform, wrapInRuntimeConfig } from './lib/config.js'
+import { basename, dirname, resolve as resolvePath } from 'node:path'
+import { transform as v3Transform, transformV4, wrapInRuntimeConfig } from './lib/config.js'
 import { NodeInspectorFlagsNotSupportedError } from './lib/errors.js'
 import { Runtime } from './lib/runtime.js'
 import { schema } from './lib/schema.js'
@@ -59,7 +67,86 @@ function handleSignal (runtime, config) {
   })
 }
 
+/*
+  v4 configuration is code, evaluated by the loader in foundation: it walks to the deciding file,
+  resolves both views of the env ladder, evaluates the root in a worker and fans out one worker per
+  per-app file. Everything the runtime transform used to discover — the application list, each
+  application's capability, its schema and its worker environment — arrives already resolved.
+
+  Routing by filename keeps the v3 path intact while the in-tree JSON fixtures are converted; the
+  v3 half is what a later commit deletes, not something this one has to keep working around.
+*/
+/*
+  A configuration named outright does not have to carry one of the four discoverable names -- that
+  is what discovery is for, and --config exists precisely to point at something discovery would not
+  find. What decides the dialect is the extension: v4 configuration is code, and v3 configuration is
+  a document.
+*/
+function isV4ConfigurationPath (path) {
+  return isConfigurationFileName(basename(path)) || /\.(js|mjs|ts|mts)$/.test(path)
+}
+
+async function findV4ConfigurationFile (configOrRoot, sourceOrConfig) {
+  // A programmatic object source is not this path: the v4 object entry point is
+  // loadObjectConfiguration, which skips the root eval worker entirely.
+  if (sourceOrConfig && typeof sourceOrConfig !== 'string') {
+    return null
+  }
+
+  if (typeof sourceOrConfig === 'string') {
+    const named = resolvePath(configOrRoot, sourceOrConfig)
+
+    return isV4ConfigurationPath(named) ? named : null
+  }
+
+  if (typeof configOrRoot !== 'string') {
+    return null
+  }
+
+  if (isV4ConfigurationPath(configOrRoot)) {
+    return configOrRoot
+  }
+
+  /*
+    Only an actual directory is a place to search from. findDecidingFile walks toward the env root,
+    so handing it a path that does not exist would answer with whatever project sits above it: a
+    typo'd --config would boot the parent rather than failing. v3 looks in the named directory and
+    nowhere else, and a wrong path has to stay an error.
+  */
+  const stats = await stat(configOrRoot).catch(() => null)
+
+  if (!stats?.isDirectory()) {
+    return null
+  }
+
+  try {
+    const deciding = await findDecidingFile(configOrRoot, { throwOnMissing: false })
+
+    return deciding?.path ?? null
+  } catch (error) {
+    /*
+      The walk refuses a v3 configuration wherever it consults, which is right once v3 is gone and
+      wrong while it is still supported: here a v3 file means "this project is not v4", and the v3
+      loader below is the one that should answer. Deleting this catch is part of deleting the v3
+      path, and at that point the refusal becomes the correct answer again.
+    */
+    if (error.code === 'PLT_LEGACY_CONFIGURATION_FILE') {
+      return null
+    }
+
+    throw error
+  }
+}
+
 export async function loadConfiguration (configOrRoot, sourceOrConfig, context) {
+  // Checked before the v3 resolver, which throws when it finds no v3 file — a v4-only project has
+  // none by construction.
+  const v4ConfigurationFile = await findV4ConfigurationFile(configOrRoot, sourceOrConfig)
+
+  if (v4ConfigurationFile) {
+    return loadV4RuntimeConfiguration(v4ConfigurationFile, context)
+  }
+
   const { root, source } = await resolve(configOrRoot, sourceOrConfig, 'runtime')
 
   // First of all, load the configuration without any validation
@@ -81,7 +168,7 @@ export async function loadConfiguration (configOrRoot, sourceOrConfig, context)
 
   return utilsLoadConfiguration(source, context?.schema ?? schema, {
     validationOptions,
-    transform,
+    transform: v3Transform,
     upgrade,
     replaceEnv: true,
     root,
@@ -89,6 +176,86 @@ export async function loadConfiguration (configOrRoot, sourceOrConfig, context)
   })
 }
 
+async function loadV4RuntimeConfiguration (configurationFile, context) {
+  const production = context?.isProduction ?? context?.production ?? false
+
+  /*
+    The environment the loader treats as real. An embedder can add to it, and can ask for a
+    hermetic runtime that sees none of this process's -- v3 honours both through loadEnv, and a v4
+    runtime that ignored them would quietly hand every worker the parent's environment.
+  */
+  const realEnv = context?.ignoreProcessEnv ? { ...context?.env } : { ...process.env, ...context?.env }
+
+  const loaded = await loadV4Configuration({
+    cwd: dirname(configurationFile),
+    configPath: configurationFile,
+    realEnv,
+    command: context?.command ?? (production ? 'start' : 'dev'),
+    mode: context?.mode,
+    production,
+    customEnvFile: context?.envFile,
+    /*
+      Validation imports each capability's schema, so it needs the capability installed — not
+      merely declared, which is all the detector needs. That moves the moment a capability must be
+      resolvable earlier than v3 ever needed it: v3 loaded fine and failed later, in the worker.
+
+      A caller that is loading only to discover the topology — a tool about to install those
+      dependencies, for instance — can say so rather than being made to install first.
+    */
+    validateCapabilities: context?.validateCapabilities ?? true,
+    // The runtime is where the bundled capability copies live, so it is the fallback scope for
+    // both the schema import and the version stamp — the application's own dependencies still
+    // come first.
+    runtimeScope: import.meta.filename,
+    onWarning: warning => abstractLogger.warn(warning.message),
+    onInfo: info => abstractLogger.info(info.message)
+  })
+
+  const config = loaded.config
+
+  /*
+    The documented pipeline is validation with useDefaults, then kMetadata, then transform. The eval
+    worker's own check is a shape check that injects nothing — deliberately, so the resolve
+    projection carries authored values — so this is where the runtime schema's defaults arrive, and
+    without it the runtime reaches for settings like gracefulShutdown that nothing supplied.
+  */
+  validateCapabilityConfiguration(config, context?.schema ?? schema, {
+    id: 'runtime',
+    module: '@platformatic/runtime',
+    root: loaded.root
+  })
+
+  // kMetadata is symbol-keyed and cannot cross a worker boundary, so each worker rebuilds it; this
+  // is the main process's copy. env is the runtime's own view — every application worker gets the
+  // per-application environment the loader resolved, not this one.
+  config[kMetadata] = {
+    root: loaded.root,
+    path: loaded.configPath,
+    env: process.env,
+    module: '@platformatic/runtime',
+    /*
+      The evaluation context, kept beside the envelope rather than inside it: applications added
+      after boot are evaluated with the same command, mode and production flags the boot pass used,
+      and its presence is also what tells the add path this runtime is v4 at all. A v3 runtime has
+      no such context and keeps resolving configuration files worker-side.
+    */
+    v4: {
+      command: context?.command ?? (production ? 'start' : 'dev'),
+      mode: loaded.mode,
+      production: loaded.production
+    }
+  }
+
+  /*
+    A caller-supplied transform replaces the built-in one, exactly as it does on the v3 path where
+    it arrives as part of ...context. Ignoring it here meant a test helper or an embedder that
+    customized the configuration was silently not consulted.
+  */
+  const apply = context?.transform ?? transformV4
+
+  return apply(config, null, context)
+}
+
 export async function loadApplicationsCommands (executableName = '', configurationFile = null) {
   const applications = {}
   const commands = {}
@@ -123,8 +290,16 @@ export async function loadApplicationsCommands (executableName = '', configurati
 
   for (const application of config.applications) {
     try {
-      const applicationConfig = await utilsLoadConfiguration(application.config)
-      const pkg = await loadConfigurationModule(application.path, applicationConfig)
+      /*
+        A v4 application arrives with its configuration already evaluated and its capability
+        already named, so there is nothing to read and nothing to infer. Reading application.config
+        as a path threw into the catch below, which skipped the application silently -- the command
+        it contributes then simply did not exist, and the CLI said the command was unknown.
+      */
+      const applicationConfig = application.resolvedConfig ?? (await utilsLoadConfiguration(application.config))
+      const pkg = application.module
+        ? await importCapabilityPackage(application.path, application.module)
+        : await loadConfigurationModule(application.path, applicationConfig)
 
       if (pkg.createCommands) {
         const definition = await pkg.createCommands(application.id)
@@ -175,7 +350,17 @@ export async function create (configOrRoot, sourceOrConfig, context) {
   return runtime
 }
 
-export { prepareApplication, transform, wrapInRuntimeConfig } from './lib/config.js'
+export { prepareApplication, wrapInRuntimeConfig } from './lib/config.js'
+
+/*
+  The exported transform dispatches on the dialect. Callers wrap it -- they call it and then adjust
+  the result -- and a wrapper that reached the v3 transform with a v4 configuration would run the
+  wrong pipeline over it: autoload expansion and enabled filtering have already happened in the
+  eval worker. v4 configurations are recognizable by the evaluation context on kMetadata.
+*/
+export async function transform (config, schema, context) {
+  return config?.[kMetadata]?.v4 ? transformV4(config, schema, context) : v3Transform(config, schema, context)
+}
 export * as errors from './lib/errors.js'
 export { RuntimeGenerator as Generator, WrappedGenerator } from './lib/generator.js'
 export { setupLoopbackMessaging } from './lib/loopback-messaging.js'

package/lib/config.js

@@ -11,18 +11,22 @@ import {
 } from '@platformatic/foundation'
 import { readdir, readFile } from 'node:fs/promises'
 import { createRequire } from 'node:module'
+import { loadAdditionalApplications } from '@platformatic/foundation/lib/v4/index.js'
 import { isAbsolute, join, resolve as resolvePath } from 'node:path'
+import { fileURLToPath } from 'node:url'
 
 import {
   InspectAndInspectBrkError,
   InspectorHostError,
   InspectorPortError,
-  InvalidArgumentError,
-  InvalidEntrypointError
+  InvalidArgumentError
 } from './errors.js'
 import { schema } from './schema.js'
 import { upgrade } from './upgrade.js'
 
+// The runtime package's own entry point, which is where the bundled capability copies live.
+const runtimeScopePath = fileURLToPath(new URL('../index.js', import.meta.url))
+
 // Validate and coerce workers values early to avoid runtime hangs when invalid
 function coercePositiveInteger (value) {
   if (typeof value === 'number') {
@@ -141,17 +145,6 @@ export async function wrapInRuntimeConfig (config, context) {
     // on purpose, the package.json might be missing
   }
 
-  // Carry over only the server properties that the user actually set, so
-  // we do not end up with a `{ hostname: undefined, ... }` object that then
-  // gets populated by schema defaults or trips truthy checks downstream.
-  const server = {}
-  if (config.server) {
-    for (const key of ['hostname', 'port', 'http2', 'https']) {
-      if (config.server[key] !== undefined) {
-        server[key] = config.server[key]
-      }
-    }
-  }
   const production = context?.isProduction ?? context?.production
 
   const runtimeConfig = config.runtime ?? {}
@@ -160,10 +153,8 @@ export async function wrapInRuntimeConfig (config, context) {
   /* c8 ignore next */
   const wrapped = {
     $schema: schema.$id,
-    ...(Object.keys(server).length > 0 ? { server } : {}),
     watch: !production,
     ...omitProperties(runtimeConfig, runtimeUnwrappablePropertiesList),
-    entrypoint: applicationId,
     applications: [
       {
         id: applicationId,
@@ -226,6 +217,49 @@ export function parseInspectorOptions (config, inspect, inspectBreak) {
   config.watch = false
 }
 
+/*
+  The one entry point for applications added while the runtime is running, shared by the HTTP route
+  and the management ITC handler so the two cannot drift.
+
+  Under v4 an added application is evaluated exactly as boot evaluates one -- its configuration
+  file is found in its own directory, its environment is resolved main-side, and it arrives with
+  resolvedConfig. Skipping that leaves the worker to look for a v3 file name that v4 never writes,
+  which fails as an unhelpful "unable to initialize the worker".
+*/
+export async function prepareAddedApplications (config, entries, existingIds = []) {
+  const metadata = config[kMetadata]
+
+  if (!metadata?.v4) {
+    const prepared = []
+
+    for (const entry of entries) {
+      prepared.push(await prepareApplication(config, entry, config.workers))
+    }
+
+    return prepared
+  }
+
+  const { applications } = await loadAdditionalApplications({
+    configPath: metadata.path,
+    entries,
+    existingIds,
+    rootEnvBlock: config.env,
+    command: metadata.v4.command,
+    mode: metadata.v4.mode,
+    production: metadata.v4.production,
+    // The runtime is the fallback scope for capability resolution, the same as at boot.
+    runtimeScope: runtimeScopePath
+  })
+
+  const prepared = []
+
+  for (const application of applications) {
+    prepared.push(await prepareV4Application(config, application, config.workers))
+  }
+
+  return prepared
+}
+
 export async function prepareApplication (config, application, defaultWorkers) {
   // We need to have absolute paths here, ot the `loadConfig` will fail
   // Make sure we don't resolve if env var was not replaced
@@ -247,10 +281,10 @@ export async function prepareApplication (config, application, defaultWorkers) {
       let pkg
 
       if (application.config) {
-        const config = await loadConfiguration(application.config)
-        pkg = await loadConfigurationModule(application.path, config)
+        const applicationConfig = await loadConfiguration(application.config)
+        pkg = await loadConfigurationModule(application.path, applicationConfig)
 
-        application.type = extractModuleFromSchemaUrl(config, true).module
+        application.type = extractModuleFromSchemaUrl(applicationConfig, true).module
         application.skipTelemetryHooks = pkg.skipTelemetryHooks
       } else {
         const { moduleName, capability } = await importCapabilityAndConfig(application.path)
@@ -277,10 +311,16 @@ export async function prepareApplication (config, application, defaultWorkers) {
     }
   }
 
+  return finalizeApplication(config, application, defaultWorkers)
+}
+
+// Everything an application needs regardless of how its capability was determined. v3 discovers
+// that by loading the application's config file; v4 has it from the loader's envelope before any
+// worker exists.
+export function finalizeApplication (config, application, defaultWorkers) {
   // Validate and coerce per-service workers
   parseWorkers(application, `Service "${application.id}"`, defaultWorkers)
 
-  application.entrypoint = application.id === config.entrypoint
   application.dependencies ??= []
   application.localUrl = `http://${application.id}.plt.local`
 
@@ -295,6 +335,39 @@ export async function prepareApplication (config, application, defaultWorkers) {
   return application
 }
 
+/*
+  The v4 preparation. The loader resolved the path, selected the capability and imported its schema
+  subpath — which carries skipTelemetryHooks and modulesToLoad — all main-side, before any worker
+  existed. So there is nothing to discover here, and in particular no application config file to
+  re-read: that is the whole point of evaluating configuration exactly once per load.
+*/
+export async function prepareV4Application (config, application, defaultWorkers) {
+  // resolvedConfig replaces v3's config file path in workerData: the worker receives the validated
+  // capability payload as data and never re-reads a file.
+  application.resolvedConfig = application.config ?? {}
+  application.config = undefined
+  application.type = application.module ?? 'unknown'
+  application.skipTelemetryHooks = application.capabilityMetadata?.skipTelemetryHooks ?? false
+
+  // This is needed to work around a Rust bug on dylibs, as in the v3 path.
+  const modulesToLoad = application.capabilityMetadata?.modulesToLoad ?? []
+
+  if (modulesToLoad.length > 0 && application.path) {
+    const _require = createRequire(application.path)
+
+    for (const m of modulesToLoad) {
+      try {
+        loadModule(_require, _require.resolve(m)).catch(() => {})
+      } catch {
+        // A module the capability names but the application cannot resolve is not fatal here; the
+        // worker reports it with its own context when it actually needs it.
+      }
+    }
+  }
+
+  return finalizeApplication(config, application, defaultWorkers)
+}
+
 function isApplicationEnabled (application, environment) {
   const { enabled } = application
 
@@ -357,7 +430,7 @@ export async function transform (config, _, context) {
         }
 
         const scaleConfig = config.verticalScaler.applications[appId]
-        const workersConfig = appConfig.workers
+        const workersConfig = appConfig.workers ??= {}
 
         workersConfig.minimum ??= scaleConfig.minWorkers ?? config.workers.minimum
         workersConfig.maximum ??= scaleConfig.maxWorkers ?? config.workers.maximum
@@ -416,54 +489,22 @@ export async function transform (config, _, context) {
     }
   }
 
+  return finalizeConfiguration(config, applications, context, production, prepareApplication)
+}
+
+// The half of the transform the loader does not own: inspector options, worker counts, the
+// per-application preparation, and the runtime-level normalizations. v4 reaches this directly,
+// having already expanded autoload and resolved enabled in the eval worker.
+export async function finalizeConfiguration (config, applications, context, production, prepare) {
   config.inspectorOptions = undefined
   parseInspectorOptions(config, context?.inspect, context?.inspectBreak)
 
-  let hasValidEntrypoint = false
-
   // Root-level workers
   parseWorkers(config, 'Runtime', { static: 1, dynamic: false })
   const defaultWorkers = config.workers
 
   for (let i = 0; i < applications.length; ++i) {
-    const application = await prepareApplication(config, applications[i], defaultWorkers)
-
-    if (application.entrypoint) {
-      hasValidEntrypoint = true
-    }
-  }
-
-  // If there is no entrypoint, autodetect one
-  if (!config.entrypoint) {
-    // If there is only one application, it becomes the entrypoint
-    if (applications.length === 1) {
-      applications[0].entrypoint = true
-      config.entrypoint = applications[0].id
-      hasValidEntrypoint = true
-    } else {
-      // Search if exactly application uses @platformatic/gateway
-      const gateways = []
-
-      for (const application of applications) {
-        if (!application.config) {
-          continue
-        }
-
-        if (application.type === '@platformatic/gateway') {
-          gateways.push(application.id)
-        }
-      }
-
-      if (gateways.length === 1) {
-        applications.find(s => s.id === gateways[0]).entrypoint = true
-        config.entrypoint = gateways[0]
-        hasValidEntrypoint = true
-      }
-    }
-  }
-
-  if (!hasValidEntrypoint && config.entrypoint && !context.allowMissingEntrypoint) {
-    throw new InvalidEntrypointError(config.entrypoint)
+    await prepare(config, applications[i], defaultWorkers)
   }
 
   if (typeof config.metrics === 'boolean') {
@@ -503,3 +544,27 @@ export async function transform (config, _, context) {
 
   return config
 }
+
+/*
+  The v4 transform. What is absent is the point:
+
+  - no alias merging, because `services` and `web` do not exist in v4;
+  - no autoload expansion and no `enabled` filtering, because both ran in the root eval worker,
+    which is the only place either runs. Leaving them reachable here would let a second expansion
+    re-merge entries and read the filesystem after the authoritative snapshot already exists;
+  - no verticalScaler migration, which the schema audit removes.
+
+  The `autoload` declaration survives as data beside the expanded list — `GET /metadata` reports it
+  and `applications:add --save` needs it to decide whether a new application belongs in a mapping
+  or as an explicit entry. It is carried, never re-executed.
+*/
+export async function transformV4 (config, _, context) {
+  const production = context?.isProduction ?? context?.production
+  const applications = config.applications ?? []
+
+  if (typeof config.watch === 'undefined') {
+    config.watch = !production
+  }
+
+  return finalizeConfiguration(config, applications, context, production, prepareV4Application)
+}