@guanjinke/artifact-client 1.18.0 → 1.19.0

package/dist/environment/update.js

@@ -949,650 +949,655 @@ class EnvironmentUpdater {
         const foreignStore = options.provider === undefined ? [] : parsed.filter(spec => spec.localPath === undefined && !(0, catalog_1.providerAllows)(spec.module, options.provider));
         if (foreignStore.length)
             throw new Error((0, catalog_1.foreignStoreError)(foreignStore[0].module, options.provider));
-        const entry = await this.registry.get(name);
-        onProgress?.(`Validating environment ${entry.name} at ${entry.root}`);
-        await (0, validate_1.validateEnvironmentRoot)(entry, this.registry.directory);
-        await (0, validate_1.validateEnvironmentOwnership)(entry, this.registry.directory);
-        await (0, validate_1.validateEnvironmentTree)(entry.root);
-        const manifest = await (0, manifest_1.readManifest)(entry.root);
-        const artifacts = [...(manifest.artifacts ?? [])];
-        const installed = new Set(artifacts.map(artifact => artifact.module));
-        const skipped = [];
-        if (parsed.some(spec => spec.module === 'all')) {
-            // `all` means every configured module from remote; modules that already
-            // point at a local developer build are left exactly as they are.
-            const localModules = new Set([...Object.keys(manifest.moduleSources ?? {}), ...(entry.localModules ?? [])]);
-            const configured = [...new Set(artifacts.map(artifact => artifact.module))].filter(module => exports.updatableModules.includes(module)).sort();
-            for (const module of configured) {
-                if (localModules.has(module))
-                    skipped.push({ module, reason: 'local' });
-                else if (!(0, catalog_1.providerAllows)(module, options.provider))
-                    skipped.push({ module, reason: 'provider' });
-            }
-            const selected = configured.filter(module => !localModules.has(module) && (0, catalog_1.providerAllows)(module, options.provider));
-            if (!selected.length)
-                throw new Error(`Module spec all matched no updatable modules: ${configured.length ? skipped.map(item => item.reason === 'local' ? `${item.module} has a local source` : `${item.module} is not published in this store`).join('; ') : 'this environment has no installed module to refresh'}.`);
-            parsed = selected.map(module => ({ module }));
-            const localSkipped = skipped.filter(item => item.reason === 'local').map(item => item.module);
-            const foreignSkipped = skipped.filter(item => item.reason === 'provider').map(item => item.module);
-            onProgress?.(`Updating all configured modules from remote: ${selected.join(', ')}${localSkipped.length ? ` (skipping local: ${localSkipped.join(', ')})` : ''}${foreignSkipped.length ? ` (not published in this store: ${foreignSkipped.join(', ')})` : ''}`);
-        }
-        const localOverrides = new Map();
-        const selectedTargets = new Set();
-        for (const spec of parsed) {
-            if (['sheets', 'documents'].includes(spec.module) && entry.edition !== 'en')
-                throw new Error(`Module ${spec.module} requires an EN edition environment; ${entry.name} is ${entry.edition}.`);
-            if (spec.module === 'reportsheet' && entry.edition !== 'cn')
-                throw new Error(`Module reportsheet requires a CN edition environment; ${entry.name} is ${entry.edition}.`);
-            // A module the environment's major does not publish is refused the same way,
-            // before a local or remote resolution touches anything.
-            if (!(0, catalog_1.majorAllows)(spec.module, entry.major))
-                throw new Error((0, catalog_1.foreignMajorError)(spec.module, entry.major));
-            if (spec.localPath === undefined)
-                continue;
-            const resolution = await resolveLocalSource(entry, spec.module, spec.assembly, spec.localPath);
-            for (const destination of resolution.inactive)
-                onProgress?.(`${spec.module}: ${destination} stays deployed (not selected by ${resolution.source})`);
-            const targets = localOverrides.get(spec.module) ?? [];
-            for (const target of resolution.targets) {
-                if (selectedTargets.has(target.destination.toLowerCase()))
-                    throw new Error(`Local target ${target.assembly} of module ${target.module} is selected twice in one update; give one spec per assembly.`);
-                selectedTargets.add(target.destination.toLowerCase());
-                targets.push(target);
-            }
-            localOverrides.set(spec.module, targets);
-        }
-        const remote = parsed.filter(spec => spec.localPath === undefined);
-        // Internal modules are never named by a spec (they are refused while the
-        // module specs are parsed) and `all` never selects them, but the updater
-        // still deploys them on its own. `dashboard-resource` ships the 3D scene and
-        // map trees *inside* the Server directory, and a Server refresh replaces that
-        // whole directory: an environment that has it therefore re-deploys it from
-        // its own artifact whenever the Server is refreshed in the same call, because
-        // there is no other copy to restore the trees from. A create-only trailing
-        // module is different: it seeds data the product imported once, so a Server
-        // refresh simply drops what it had seeded.
-        const autoRefreshed = [];
-        if (remote.some(spec => spec.module === 'server')) {
-            for (const module of plan_1.trailingModules) {
-                if (catalog_1.catalog[module].createOnly || !installed.has(module) || parsed.some(spec => spec.module === module))
-                    continue;
-                parsed.push({ module });
-                remote.push({ module });
-                autoRefreshed.push(module);
-                onProgress?.(`${module} is refreshed with the Server package: its trees deploy inside the Server directory`);
+        const original = await this.registry.get(name);
+        return this.registry.locked(`env-${original.id}`, async () => {
+            const entry = await this.registry.get(name);
+            if (entry.id !== original.id || entry.root !== original.root)
+                throw new Error('Environment changed during operation.');
+            onProgress?.(`Validating environment ${entry.name} at ${entry.root}`);
+            await (0, validate_1.validateEnvironmentRoot)(entry, this.registry.directory);
+            await (0, validate_1.validateEnvironmentOwnership)(entry, this.registry.directory);
+            await (0, validate_1.validateEnvironmentTree)(entry.root);
+            const manifest = await (0, manifest_1.readManifest)(entry.root);
+            const artifacts = [...(manifest.artifacts ?? [])];
+            const installed = new Set(artifacts.map(artifact => artifact.module));
+            const skipped = [];
+            if (parsed.some(spec => spec.module === 'all')) {
+                // `all` means every configured module from remote; modules that already
+                // point at a local developer build are left exactly as they are.
+                const localModules = new Set([...Object.keys(manifest.moduleSources ?? {}), ...(entry.localModules ?? [])]);
+                const configured = [...new Set(artifacts.map(artifact => artifact.module))].filter(module => exports.updatableModules.includes(module)).sort();
+                for (const module of configured) {
+                    if (localModules.has(module))
+                        skipped.push({ module, reason: 'local' });
+                    else if (!(0, catalog_1.providerAllows)(module, options.provider))
+                        skipped.push({ module, reason: 'provider' });
+                }
+                const selected = configured.filter(module => !localModules.has(module) && (0, catalog_1.providerAllows)(module, options.provider));
+                if (!selected.length)
+                    throw new Error(`Module spec all matched no updatable modules: ${configured.length ? skipped.map(item => item.reason === 'local' ? `${item.module} has a local source` : `${item.module} is not published in this store`).join('; ') : 'this environment has no installed module to refresh'}.`);
+                parsed = selected.map(module => ({ module }));
+                const localSkipped = skipped.filter(item => item.reason === 'local').map(item => item.module);
+                const foreignSkipped = skipped.filter(item => item.reason === 'provider').map(item => item.module);
+                onProgress?.(`Updating all configured modules from remote: ${selected.join(', ')}${localSkipped.length ? ` (skipping local: ${localSkipped.join(', ')})` : ''}${foreignSkipped.length ? ` (not published in this store: ${foreignSkipped.join(', ')})` : ''}`);
             }
-        }
-        // A Server refresh restores the unpatched file the Server package ships, so
-        // an installed deferred module is re-applied in the same call. Its version is
-        // resolved from the *new* package below, never from the old tree. Without a
-        // Server refresh it is only applied when the caller names it explicitly.
-        const autoReplaced = [];
-        if (remote.some(spec => spec.module === 'server')) {
-            for (const module of Object.keys(catalog_1.catalog)) {
-                if (!catalog_1.catalog[module].deferred || !installed.has(module) || parsed.some(spec => spec.module === module))
+            const localOverrides = new Map();
+            const selectedTargets = new Set();
+            for (const spec of parsed) {
+                if (['sheets', 'documents'].includes(spec.module) && entry.edition !== 'en')
+                    throw new Error(`Module ${spec.module} requires an EN edition environment; ${entry.name} is ${entry.edition}.`);
+                if (spec.module === 'reportsheet' && entry.edition !== 'cn')
+                    throw new Error(`Module reportsheet requires a CN edition environment; ${entry.name} is ${entry.edition}.`);
+                // A module the environment's major does not publish is refused the same way,
+                // before a local or remote resolution touches anything.
+                if (!(0, catalog_1.majorAllows)(spec.module, entry.major))
+                    throw new Error((0, catalog_1.foreignMajorError)(spec.module, entry.major));
+                if (spec.localPath === undefined)
                     continue;
-                parsed.push({ module });
-                remote.push({ module });
-                autoReplaced.push(module);
-                onProgress?.(`${module} is re-applied with the Server package: the new package replaces the file it patches`);
-            }
-        }
-        // Smart documents cannot run without the collaboration service, which
-        // create-env deploys and declares in the Server configuration alongside
-        // documents. Installing documents into an environment with no collaboration
-        // deployment would produce a broken environment, so refuse — after the
-        // edition gate above, so a CN environment still reports the EN requirement.
-        if (parsed.some(spec => spec.module === 'documents') && !installed.has('collaboration')) {
-            throw new Error(`Module documents requires the collaboration service, which ${entry.name} has not deployed. Recreate the environment with create-env: selecting documents deploys collaboration automatically.`);
-        }
-        const state = await (0, validate_1.observeRuntimeState)(entry, this.processes);
-        if (remote.length && state !== 'ready' && state !== 'stopped')
-            throw new Error(`Cannot update modules from a remote source while ${entry.name} is ${state}: deployed files may be in use. Run \`afm env stop ${entry.name}\` first.`);
-        if (!remote.length && state !== 'ready' && state !== 'stopped' && state !== 'running')
-            throw new Error(`Cannot update modules while ${entry.name} is ${state}: the runtime identity must be verified before its files are changed. Run \`afm env stop ${entry.name}\` first.`);
-        const downloads = [...(manifest.downloads ?? [])];
-        const selectedModules = stringListOrUndefined(manifest.selectedModules);
-        const autoAddedModules = stringListOrUndefined(manifest.autoAddedModules);
-        const moduleSources = { ...(manifest.moduleSources ?? {}) };
-        // What a fresh environment would have selected for itself. An update records
-        // a first install the way `create-env` does: a selectable module joins the
-        // selection, a core component or an automatic dependency is added instead.
-        const selectable = selectableModules();
-        // The manifest records the .NET requirements read from each artifact's
-        // runtimeconfig files, so an update replaces the entries of the modules it
-        // refreshes and leaves every other module's alone.
-        let requirements = Array.isArray(manifest.requirements) ? manifest.requirements.filter((line) => typeof line === 'string') : [];
-        // Read once: the up-to-date check below inspects the same configuration the
-        // patch would rewrite later, and an environment without it is not current.
-        const configured = await fs.readFile(path.join(entry.root, 'conf', 'Wyn.conf'), 'utf8');
-        const workspace = !dryRun && remote.length > 0 ? await fs.mkdtemp(path.join(path.dirname(entry.root), '.afm-env-')) : undefined;
-        const warnings = [];
-        try {
-            const resolved = new Map();
-            const staged = new Map();
-            const replacements = new Map();
-            // Modules already at the resolved version with a complete deployment: they
-            // are reported as skipped and never downloaded, staged or written.
-            const current = new Map();
-            if (remote.length) {
-                const client = clientFactory();
-                const direct = remote.filter(spec => !catalog_1.catalog[spec.module].deferred);
-                for (const spec of direct) {
-                    onProgress?.(`Resolving ${catalog_1.catalog[spec.module].plugin}`);
-                    resolved.set(spec.module, await resolveRemoteArtifact(client, entry, spec));
+                const resolution = await resolveLocalSource(entry, spec.module, spec.assembly, spec.localPath);
+                for (const destination of resolution.inactive)
+                    onProgress?.(`${spec.module}: ${destination} stays deployed (not selected by ${resolution.source})`);
+                const targets = localOverrides.get(spec.module) ?? [];
+                for (const target of resolution.targets) {
+                    if (selectedTargets.has(target.destination.toLowerCase()))
+                        throw new Error(`Local target ${target.assembly} of module ${target.module} is selected twice in one update; give one spec per assembly.`);
+                    selectedTargets.add(target.destination.toLowerCase());
+                    targets.push(target);
                 }
-                // A module the caller pinned is always deployed: the pin is the explicit
-                // request for that build. Modules the same call re-deploys because of a
-                // Server refresh are never current either — their files are about to be
-                // replaced. Everything else is compared with the deployed record and its
-                // actual files and configuration entries before anything is downloaded.
-                for (const spec of direct) {
-                    if (spec.version !== undefined || autoRefreshed.includes(spec.module) || autoReplaced.includes(spec.module))
+                localOverrides.set(spec.module, targets);
+            }
+            const remote = parsed.filter(spec => spec.localPath === undefined);
+            // Internal modules are never named by a spec (they are refused while the
+            // module specs are parsed) and `all` never selects them, but the updater
+            // still deploys them on its own. `dashboard-resource` ships the 3D scene and
+            // map trees *inside* the Server directory, and a Server refresh replaces that
+            // whole directory: an environment that has it therefore re-deploys it from
+            // its own artifact whenever the Server is refreshed in the same call, because
+            // there is no other copy to restore the trees from. A create-only trailing
+            // module is different: it seeds data the product imported once, so a Server
+            // refresh simply drops what it had seeded.
+            const autoRefreshed = [];
+            if (remote.some(spec => spec.module === 'server')) {
+                for (const module of plan_1.trailingModules) {
+                    if (catalog_1.catalog[module].createOnly || !installed.has(module) || parsed.some(spec => spec.module === module))
                         continue;
-                    const artifact = resolved.get(spec.module);
-                    if (await moduleIsCurrent(entry, manifest, artifact, editionOf(entry), configured, this.platform)) {
-                        current.set(spec.module, artifact.version);
-                        onProgress?.(`${artifact.module}/${artifact.version}: already deployed; nothing downloaded`);
-                    }
+                    parsed.push({ module });
+                    remote.push({ module });
+                    autoRefreshed.push(module);
+                    onProgress?.(`${module} is refreshed with the Server package: its trees deploy inside the Server directory`);
                 }
-                if (!dryRun)
-                    for (const spec of direct)
-                        if (!current.has(spec.module))
-                            staged.set(spec.module, await stageRemoteArtifact(client, resolved.get(spec.module), editionOf(entry), workspace, onProgress));
-                // A deferred module resolves after the direct artifacts are staged, so a
-                // Server refresh contributes the *new* package's version. Without a
-                // Server refresh the already deployed tree is the authority. A dry-run
-                // that refreshes the Server cannot know that version without downloading
-                // the package, so it reports the deferred resolution and stops there.
-                for (const spec of remote.filter(candidate => catalog_1.catalog[candidate.module].deferred)) {
-                    const module = spec.module;
-                    const source = catalog_1.catalog[module];
-                    const label = (0, catalog_1.moduleLabel)(source);
-                    const server = staged.get('server');
-                    const refreshesServer = remote.some(candidate => candidate.module === 'server');
-                    const localServer = moduleSources.server?.type === 'local' ? moduleSources.server.path : undefined;
-                    let version;
-                    let resolvedFrom = 'the deployed Server package';
-                    if (server) {
-                        version = await (0, deferred_1.deferredVersionAt)(source, stagedServerFile(server, module));
-                        resolvedFrom = 'the refreshed Server package';
-                        // The replacement must overwrite an existing regular file in the new
-                        // package; checking the staged tree catches a package that no longer
-                        // ships it before anything has been written.
-                        for (const mapping of (0, deferred_1.replacementMappings)(source)) {
-                            const file = stagedServerPath(server, mapping.destination);
-                            const stat = await lstatOrUndefined(file);
-                            if (!stat)
-                                throw new Error(`Module ${label} could not be applied: the Server package holds no file to replace.`);
-                            if (!stat.isFile() || stat.isSymbolicLink())
-                                throw new Error(`Module ${label} could not be applied: the Server package holds no regular file to replace.`);
-                        }
-                    }
-                    else if (refreshesServer) {
-                        onProgress?.(`${label}: version resolves from the refreshed Server package at execution time`);
-                        replacements.set(module, { version: '' });
-                        continue;
-                    }
-                    else if (localServer) {
-                        // A local Server build is copied over the deployed tree on every start,
-                        // so the version that must be cached now is the one that build
-                        // declares — not the version of the currently deployed package.
-                        version = await (0, deferred_1.deferredVersionAt)(source, localServerPath(localServer, source.deferred.versionFile));
-                        resolvedFrom = 'the local Server build directory';
-                    }
-                    else
-                        version = await (0, deferred_1.deferredVersion)(source, entry.root);
-                    // Already applied and untouched: the recorded download still hashes to
-                    // the deployed file, so there is nothing to download or copy. A call
-                    // that refreshes the Server always re-applies it (autoReplaced), and a
-                    // local Server build resolves a version this tree does not hold.
-                    if (!refreshesServer && !localServer && spec.version === undefined && !autoReplaced.includes(module)
-                        && await replacementIsCurrent(entry, manifest, module, version)) {
-                        current.set(module, version);
-                        onProgress?.(`${label}/${version}: already applied; nothing downloaded`);
-                        continue;
-                    }
-                    const payloads = await (0, deferred_1.deferredPayload)(source, version, client);
-                    if (dryRun) {
-                        onProgress?.(`${label}/${version}: resolved from ${resolvedFrom}; nothing downloaded`);
-                        replacements.set(module, { version });
+            }
+            // A Server refresh restores the unpatched file the Server package ships, so
+            // an installed deferred module is re-applied in the same call. Its version is
+            // resolved from the *new* package below, never from the old tree. Without a
+            // Server refresh it is only applied when the caller names it explicitly.
+            const autoReplaced = [];
+            if (remote.some(spec => spec.module === 'server')) {
+                for (const module of Object.keys(catalog_1.catalog)) {
+                    if (!catalog_1.catalog[module].deferred || !installed.has(module) || parsed.some(spec => spec.module === module))
                         continue;
-                    }
-                    replacements.set(module, await stageReplacement(client, module, version, payloads, workspace, onProgress));
+                    parsed.push({ module });
+                    remote.push({ module });
+                    autoReplaced.push(module);
+                    onProgress?.(`${module} is re-applied with the Server package: the new package replaces the file it patches`);
                 }
             }
-            // A Server or Monitor package is only usable when it still serves the
-            // configuration schema this environment runs, so both are checked against
-            // the deployed schema before anything is planned around them.
-            const schema = remote.some(spec => spec.module === 'server' || spec.module === 'monitoring')
-                ? environmentSchema(manifest, configured)
-                : undefined;
-            if (remote.some(spec => spec.module === 'server' || spec.module === 'monitoring') && !schema) {
-                throw new Error(`Module update for ${remote.filter(spec => spec.module === 'server' || spec.module === 'monitoring').map(spec => spec.module).join(' and ')} needs the configuration schema of ${entry.name}, which neither its manifest nor its conf/Wyn.conf records. Recreate the environment with create-env.`);
-            }
-            // A planned deferred module validates the exact Server file it replaces,
-            // with a message that names only the module; the Server's own required-file
-            // check would otherwise report the same missing file by its internal name.
-            const deferredPlanned = remote.some(spec => catalog_1.catalog[spec.module].deferred);
-            for (const spec of remote) {
-                const stagedArtifact = staged.get(spec.module);
-                if (!stagedArtifact || !schema || !(spec.module in requiredPackageFiles))
-                    continue;
-                const required = spec.module === 'server' && deferredPlanned ? [] : requiredPackageFiles[spec.module];
-                const warning = await verifyStagedPackage(spec.module, stagedArtifact, schema, required);
-                if (warning)
-                    warnings.push(warning);
+            // Smart documents cannot run without the collaboration service, which
+            // create-env deploys and declares in the Server configuration alongside
+            // documents. Installing documents into an environment with no collaboration
+            // deployment would produce a broken environment, so refuse — after the
+            // edition gate above, so a CN environment still reports the EN requirement.
+            if (parsed.some(spec => spec.module === 'documents') && !installed.has('collaboration')) {
+                throw new Error(`Module documents requires the collaboration service, which ${entry.name} has not deployed. Recreate the environment with create-env: selecting documents deploys collaboration automatically.`);
             }
-            const plans = [];
-            // A module may carry several local specs: plan it once, for all its targets.
-            // The built-in trailing modules are planned last, in the same order
-            // `create-env` assembles: their trees live inside other modules'
-            // directories, so a Server replacement must not wipe them again. A deferred
-            // module runs after `server` even when the caller wrote it first: the Server
-            // directory must hold the new package before it is patched.
-            const rank = (module) => plan_1.trailingModules.includes(module) ? 2 : catalog_1.catalog[module].deferred ? 1 : 0;
-            const planOrder = [...new Set(parsed.map(spec => spec.module))].sort((left, right) => rank(left) - rank(right));
-            for (const module of planOrder) {
-                const artifact = artifacts.find(candidate => candidate.module === module);
-                const previous = moduleSources[module] ? { local: moduleSources[module].path } : { version: artifact?.version };
-                // Already deployed by the check above: report it and keep every file, the
-                // configuration and the manifest exactly as they are.
-                if (current.has(module)) {
-                    skipped.push({ module, reason: 'current' });
-                    onProgress?.(`${module}/${current.get(module)}: already deployed; skipped`);
-                    continue;
-                }
-                const override = localOverrides.get(module);
-                if (override && module === 'server') {
-                    // A local Server build is recorded, not laid out: the build directory is
-                    // copied over `Server/` on every start (see `prepareLocalServer`), so an
-                    // update only records it and never touches the Server tree or the
-                    // configuration.
-                    if (override.length !== 1)
-                        throw new Error('Module server takes exactly one local build directory.');
-                    onProgress?.('server: the local build is copied to Server on every start');
-                    plans.push({
-                        module, previous, next: { local: override[0].path }, local: override,
-                        entries: [], copies: [], removals: [], preserved: [], copiedDirectories: [], removedDirectories: [],
-                    });
-                    continue;
-                }
-                if (override) {
-                    const removals = [];
-                    const removedDirectories = [];
-                    for (const target of override) {
-                        const destination = installationDirectory(entry.root, target.destination);
-                        if (!await exists(destination))
+            const state = await (0, validate_1.observeRuntimeState)(entry, this.processes);
+            if (remote.length && state !== 'ready' && state !== 'stopped')
+                throw new Error(`Cannot update modules from a remote source while ${entry.name} is ${state}: deployed files may be in use. Run \`afm env stop ${entry.name}\` first.`);
+            if (!remote.length && state !== 'ready' && state !== 'stopped' && state !== 'running')
+                throw new Error(`Cannot update modules while ${entry.name} is ${state}: the runtime identity must be verified before its files are changed. Run \`afm env stop ${entry.name}\` first.`);
+            const downloads = [...(manifest.downloads ?? [])];
+            const selectedModules = stringListOrUndefined(manifest.selectedModules);
+            const autoAddedModules = stringListOrUndefined(manifest.autoAddedModules);
+            const moduleSources = { ...(manifest.moduleSources ?? {}) };
+            // What a fresh environment would have selected for itself. An update records
+            // a first install the way `create-env` does: a selectable module joins the
+            // selection, a core component or an automatic dependency is added instead.
+            const selectable = selectableModules();
+            // The manifest records the .NET requirements read from each artifact's
+            // runtimeconfig files, so an update replaces the entries of the modules it
+            // refreshes and leaves every other module's alone.
+            let requirements = Array.isArray(manifest.requirements) ? manifest.requirements.filter((line) => typeof line === 'string') : [];
+            // Read once: the up-to-date check below inspects the same configuration the
+            // patch would rewrite later, and an environment without it is not current.
+            const configured = await fs.readFile(path.join(entry.root, 'conf', 'Wyn.conf'), 'utf8');
+            const workspace = !dryRun && remote.length > 0 ? await fs.mkdtemp(path.join(path.dirname(entry.root), '.afm-env-')) : undefined;
+            const warnings = [];
+            try {
+                const resolved = new Map();
+                const staged = new Map();
+                const replacements = new Map();
+                // Modules already at the resolved version with a complete deployment: they
+                // are reported as skipped and never downloaded, staged or written.
+                const current = new Map();
+                if (remote.length) {
+                    const client = clientFactory();
+                    const direct = remote.filter(spec => !catalog_1.catalog[spec.module].deferred);
+                    for (const spec of direct) {
+                        onProgress?.(`Resolving ${catalog_1.catalog[spec.module].plugin}`);
+                        resolved.set(spec.module, await resolveRemoteArtifact(client, entry, spec));
+                    }
+                    // A module the caller pinned is always deployed: the pin is the explicit
+                    // request for that build. Modules the same call re-deploys because of a
+                    // Server refresh are never current either — their files are about to be
+                    // replaced. Everything else is compared with the deployed record and its
+                    // actual files and configuration entries before anything is downloaded.
+                    for (const spec of direct) {
+                        if (spec.version !== undefined || autoRefreshed.includes(spec.module) || autoReplaced.includes(spec.module))
                             continue;
-                        removals.push(destination);
-                        removedDirectories.push(target.destination);
+                        const artifact = resolved.get(spec.module);
+                        if (await moduleIsCurrent(entry, manifest, artifact, editionOf(entry), configured, this.platform)) {
+                            current.set(spec.module, artifact.version);
+                            onProgress?.(`${artifact.module}/${artifact.version}: already deployed; nothing downloaded`);
+                        }
                     }
-                    const entries = override.map(target => {
-                        const entry = { destination: target.destination, assemblies: [target.assembly], path: target.path };
-                        if (target.kind === 'worker') {
-                            entry.role = 'worker';
-                            if (target.service)
-                                entry.service = target.service;
+                    if (!dryRun)
+                        for (const spec of direct)
+                            if (!current.has(spec.module))
+                                staged.set(spec.module, await stageRemoteArtifact(client, resolved.get(spec.module), editionOf(entry), workspace, onProgress));
+                    // A deferred module resolves after the direct artifacts are staged, so a
+                    // Server refresh contributes the *new* package's version. Without a
+                    // Server refresh the already deployed tree is the authority. A dry-run
+                    // that refreshes the Server cannot know that version without downloading
+                    // the package, so it reports the deferred resolution and stops there.
+                    for (const spec of remote.filter(candidate => catalog_1.catalog[candidate.module].deferred)) {
+                        const module = spec.module;
+                        const source = catalog_1.catalog[module];
+                        const label = (0, catalog_1.moduleLabel)(source);
+                        const server = staged.get('server');
+                        const refreshesServer = remote.some(candidate => candidate.module === 'server');
+                        const localServer = moduleSources.server?.type === 'local' ? moduleSources.server.path : undefined;
+                        let version;
+                        let resolvedFrom = 'the deployed Server package';
+                        if (server) {
+                            version = await (0, deferred_1.deferredVersionAt)(source, stagedServerFile(server, module));
+                            resolvedFrom = 'the refreshed Server package';
+                            // The replacement must overwrite an existing regular file in the new
+                            // package; checking the staged tree catches a package that no longer
+                            // ships it before anything has been written.
+                            for (const mapping of (0, deferred_1.replacementMappings)(source)) {
+                                const file = stagedServerPath(server, mapping.destination);
+                                const stat = await lstatOrUndefined(file);
+                                if (!stat)
+                                    throw new Error(`Module ${label} could not be applied: the Server package holds no file to replace.`);
+                                if (!stat.isFile() || stat.isSymbolicLink())
+                                    throw new Error(`Module ${label} could not be applied: the Server package holds no regular file to replace.`);
+                            }
                         }
-                        return entry;
-                    });
-                    plans.push({
-                        module, previous, next: { local: override.map(target => target.path).join(', ') }, local: override,
-                        entries, copies: [], removals, preserved: [], copiedDirectories: [], removedDirectories,
-                    });
-                    continue;
-                }
-                // A deferred module replaces one existing regular file and contributes
-                // no directory, plugin, worker, service or runtime requirement. Its
-                // version and payload were resolved above; nothing about the provider is
-                // recorded, and the target is checked before any write.
-                if (catalog_1.catalog[module].deferred) {
-                    const replacement = replacements.get(module);
-                    const label = (0, catalog_1.moduleLabel)(catalog_1.catalog[module]);
-                    const version = replacement?.version || undefined;
-                    const files = [];
-                    if (replacement?.files?.length) {
-                        const mappings = (0, deferred_1.replacementMappings)(catalog_1.catalog[module]);
-                        for (const file of replacement.files) {
-                            const matches = mappings.filter(mapping => mapping.source === file.name);
-                            if (matches.length !== 1)
-                                throw new Error(`Module ${label} could not be applied: the replacement target is not configured.`);
-                            const destination = installationDirectory(entry.root, matches[0].destination);
-                            const stat = await lstatOrUndefined(destination);
-                            if (!stat)
-                                throw new Error(`Module ${label} could not be applied: the Server tree holds no file to replace.`);
-                            if (!stat.isFile() || stat.isSymbolicLink())
-                                throw new Error(`Module ${label} could not be applied: the Server tree holds no regular file to replace.`);
-                            files.push({ source: file.source, destination, sha256: file.sha256 });
+                        else if (refreshesServer) {
+                            onProgress?.(`${label}: version resolves from the refreshed Server package at execution time`);
+                            replacements.set(module, { version: '' });
+                            continue;
                         }
-                    }
-                    plans.push({
-                        module, previous, next: version ? { version } : {},
-                        ...(files.length ? { replacement: { version: version, files } } : {}),
-                        entries: [], copies: [], removals: [], preserved: [], copiedDirectories: [], removedDirectories: [],
-                    });
-                    continue;
-                }
-                const remoteArtifact = resolved.get(module);
-                const stagedArtifact = staged.get(module);
-                const copies = [];
-                const removals = [];
-                const preserved = [];
-                const copiedDirectories = [];
-                const removedDirectories = [];
-                const entries = [];
-                let configurationAssets;
-                let configurationLink;
-                // Only the mappings this environment's edition deploys: the other
-                // edition's directory is never removed, copied or referenced.
-                for (const mapping of stagedArtifact?.layout ?? (0, catalog_1.editionMappings)(remoteArtifact.mappings, editionOf(entry))) {
-                    const destination = installationDirectory(entry.root, mapping.destination);
-                    // A `resource` directory the module already deployed is replaced, never
-                    // merged, and it contributes no plugin, worker, service or runtime entry.
-                    if (await exists(destination)) {
-                        removals.push(destination);
-                        removedDirectories.push(mapping.destination);
-                    }
-                    // The Server settings the environment owns are never taken from the
-                    // archive and must survive the replacement, so carry each one that is
-                    // actually deployed across the directory swap.
-                    if (stagedArtifact && mapping.role === 'server' && workspace) {
-                        for (const name of excludedCopyNames(mapping)) {
-                            if (await exists(path.join(destination, name)))
-                                preserved.push({ directory: destination, name, source: path.join(workspace, 'preserved', module, name) });
+                        else if (localServer) {
+                            // A local Server build is copied over the deployed tree on every start,
+                            // so the version that must be cached now is the one that build
+                            // declares — not the version of the currently deployed package.
+                            version = await (0, deferred_1.deferredVersionAt)(source, localServerPath(localServer, source.deferred.versionFile));
+                            resolvedFrom = 'the local Server build directory';
+                        }
+                        else
+                            version = await (0, deferred_1.deferredVersion)(source, entry.root);
+                        // Already applied and untouched: the recorded download still hashes to
+                        // the deployed file, so there is nothing to download or copy. A call
+                        // that refreshes the Server always re-applies it (autoReplaced), and a
+                        // local Server build resolves a version this tree does not hold.
+                        if (!refreshesServer && !localServer && spec.version === undefined && !autoReplaced.includes(module)
+                            && await replacementIsCurrent(entry, manifest, module, version)) {
+                            current.set(module, version);
+                            onProgress?.(`${label}/${version}: already applied; nothing downloaded`);
+                            continue;
                         }
+                        const payloads = await (0, deferred_1.deferredPayload)(source, version, client);
+                        if (dryRun) {
+                            onProgress?.(`${label}/${version}: resolved from ${resolvedFrom}; nothing downloaded`);
+                            replacements.set(module, { version });
+                            continue;
+                        }
+                        replacements.set(module, await stageReplacement(client, module, version, payloads, workspace, onProgress));
                     }
-                    if (stagedArtifact)
-                        copies.push({ source: path.join(stagedArtifact.expanded, ...mapping.source.split('/')), destination, exclude: [...excludedCopyNames(mapping), ...(mapping.exclude ?? []).map(name => name.toLowerCase())] });
-                    copiedDirectories.push(mapping.destination);
-                    if (mapping.role === 'resource')
+                }
+                // A Server or Monitor package is only usable when it still serves the
+                // configuration schema this environment runs, so both are checked against
+                // the deployed schema before anything is planned around them.
+                const schema = remote.some(spec => spec.module === 'server' || spec.module === 'monitoring')
+                    ? environmentSchema(manifest, configured)
+                    : undefined;
+                if (remote.some(spec => spec.module === 'server' || spec.module === 'monitoring') && !schema) {
+                    throw new Error(`Module update for ${remote.filter(spec => spec.module === 'server' || spec.module === 'monitoring').map(spec => spec.module).join(' and ')} needs the configuration schema of ${entry.name}, which neither its manifest nor its conf/Wyn.conf records. Recreate the environment with create-env.`);
+                }
+                // A planned deferred module validates the exact Server file it replaces,
+                // with a message that names only the module; the Server's own required-file
+                // check would otherwise report the same missing file by its internal name.
+                const deferredPlanned = remote.some(spec => catalog_1.catalog[spec.module].deferred);
+                for (const spec of remote) {
+                    const stagedArtifact = staged.get(spec.module);
+                    if (!stagedArtifact || !schema || !(spec.module in requiredPackageFiles))
                         continue;
-                    // A native out-of-process service has no assembly and is declared as an
-                    // empty node: the Server loads it from that entry and supplies the rest.
-                    if (mapping.role === 'service') {
-                        if (mapping.service)
-                            entries.push({ destination: mapping.destination, assemblies: [], path: mapping.destination, role: 'service', service: mapping.service });
+                    const required = spec.module === 'server' && deferredPlanned ? [] : requiredPackageFiles[spec.module];
+                    const warning = await verifyStagedPackage(spec.module, stagedArtifact, schema, required);
+                    if (warning)
+                        warnings.push(warning);
+                }
+                const plans = [];
+                // A module may carry several local specs: plan it once, for all its targets.
+                // The built-in trailing modules are planned last, in the same order
+                // `create-env` assembles: their trees live inside other modules'
+                // directories, so a Server replacement must not wipe them again. A deferred
+                // module runs after `server` even when the caller wrote it first: the Server
+                // directory must hold the new package before it is patched.
+                const rank = (module) => plan_1.trailingModules.includes(module) ? 2 : catalog_1.catalog[module].deferred ? 1 : 0;
+                const planOrder = [...new Set(parsed.map(spec => spec.module))].sort((left, right) => rank(left) - rank(right));
+                for (const module of planOrder) {
+                    const artifact = artifacts.find(candidate => candidate.module === module);
+                    const previous = moduleSources[module] ? { local: moduleSources[module].path } : { version: artifact?.version };
+                    // Already deployed by the check above: report it and keep every file, the
+                    // configuration and the manifest exactly as they are.
+                    if (current.has(module)) {
+                        skipped.push({ module, reason: 'current' });
+                        onProgress?.(`${module}/${current.get(module)}: already deployed; skipped`);
                         continue;
                     }
-                    const assembly = stagedArtifact?.assemblies.get(mapping.destination) ?? knownAssembly(configured, mapping, this.platform);
-                    // Plugins stay relative to the environment root; a worker entry does too,
-                    // and its service keeps using the deployed destination as working directory.
-                    // The Server service the Monitor starts is kept in step the same way.
-                    if (mapping.role === 'plugin' || mapping.role === 'worker' || mapping.role === 'server') {
-                        const entry = { destination: mapping.destination, assemblies: mapping.assemblies, path: path.posix.join(mapping.destination, assembly) };
-                        if (mapping.role === 'worker' || mapping.role === 'server') {
-                            entry.role = mapping.role;
-                            if (mapping.service)
-                                entry.service = mapping.service;
+                    const override = localOverrides.get(module);
+                    if (override && module === 'server') {
+                        // A local Server build is recorded, not laid out: the build directory is
+                        // copied over `Server/` on every start (see `prepareLocalServer`), so an
+                        // update only records it and never touches the Server tree or the
+                        // configuration.
+                        if (override.length !== 1)
+                            throw new Error('Module server takes exactly one local build directory.');
+                        onProgress?.('server: the local build is copied to Server on every start');
+                        plans.push({
+                            module, previous, next: { local: override[0].path }, local: override,
+                            entries: [], copies: [], removals: [], preserved: [], copiedDirectories: [], removedDirectories: [],
+                        });
+                        continue;
+                    }
+                    if (override) {
+                        const removals = [];
+                        const removedDirectories = [];
+                        for (const target of override) {
+                            const destination = installationDirectory(entry.root, target.destination);
+                            if (!await exists(destination))
+                                continue;
+                            removals.push(destination);
+                            removedDirectories.push(target.destination);
                         }
-                        entries.push(entry);
+                        const entries = override.map(target => {
+                            const entry = { destination: target.destination, assemblies: [target.assembly], path: target.path };
+                            if (target.kind === 'worker') {
+                                entry.role = 'worker';
+                                if (target.service)
+                                    entry.service = target.service;
+                            }
+                            return entry;
+                        });
+                        plans.push({
+                            module, previous, next: { local: override.map(target => target.path).join(', ') }, local: override,
+                            entries, copies: [], removals, preserved: [], copiedDirectories: [], removedDirectories,
+                        });
+                        continue;
                     }
-                    // The Monitor resolves its configuration from its own working directory,
-                    // so its package assets belong in the canonical `conf` and the directory
-                    // itself has to point back at it once the Monitor tree is replaced.
-                    if (mapping.role === 'monitor' && stagedArtifact) {
-                        const assets = path.join(stagedArtifact.expanded, 'conf');
-                        if ((await fs.lstat(assets).catch(() => undefined))?.isDirectory())
-                            configurationAssets = { source: assets, destination: path.join(entry.root, 'conf') };
-                        configurationLink = path.join(destination, 'conf');
+                    // A deferred module replaces one existing regular file and contributes
+                    // no directory, plugin, worker, service or runtime requirement. Its
+                    // version and payload were resolved above; nothing about the provider is
+                    // recorded, and the target is checked before any write.
+                    if (catalog_1.catalog[module].deferred) {
+                        const replacement = replacements.get(module);
+                        const label = (0, catalog_1.moduleLabel)(catalog_1.catalog[module]);
+                        const version = replacement?.version || undefined;
+                        const files = [];
+                        if (replacement?.files?.length) {
+                            const mappings = (0, deferred_1.replacementMappings)(catalog_1.catalog[module]);
+                            for (const file of replacement.files) {
+                                const matches = mappings.filter(mapping => mapping.source === file.name);
+                                if (matches.length !== 1)
+                                    throw new Error(`Module ${label} could not be applied: the replacement target is not configured.`);
+                                const destination = installationDirectory(entry.root, matches[0].destination);
+                                const stat = await lstatOrUndefined(destination);
+                                if (!stat)
+                                    throw new Error(`Module ${label} could not be applied: the Server tree holds no file to replace.`);
+                                if (!stat.isFile() || stat.isSymbolicLink())
+                                    throw new Error(`Module ${label} could not be applied: the Server tree holds no regular file to replace.`);
+                                files.push({ source: file.source, destination, sha256: file.sha256 });
+                            }
+                        }
+                        plans.push({
+                            module, previous, next: version ? { version } : {},
+                            ...(files.length ? { replacement: { version: version, files } } : {}),
+                            entries: [], copies: [], removals: [], preserved: [], copiedDirectories: [], removedDirectories: [],
+                        });
+                        continue;
                     }
-                }
-                if (module === 'dashboard' && stagedArtifact) {
-                    const contents = path.join(stagedArtifact.expanded, 'Web Contents');
-                    if ((await fs.lstat(contents).catch(() => undefined))?.isDirectory()) {
-                        const destination = path.join(entry.root, 'Web Contents');
+                    const remoteArtifact = resolved.get(module);
+                    const stagedArtifact = staged.get(module);
+                    const copies = [];
+                    const removals = [];
+                    const preserved = [];
+                    const copiedDirectories = [];
+                    const removedDirectories = [];
+                    const entries = [];
+                    let configurationAssets;
+                    let configurationLink;
+                    // Only the mappings this environment's edition deploys: the other
+                    // edition's directory is never removed, copied or referenced.
+                    for (const mapping of stagedArtifact?.layout ?? (0, catalog_1.editionMappings)(remoteArtifact.mappings, editionOf(entry))) {
+                        const destination = installationDirectory(entry.root, mapping.destination);
+                        // A `resource` directory the module already deployed is replaced, never
+                        // merged, and it contributes no plugin, worker, service or runtime entry.
                         if (await exists(destination)) {
                             removals.push(destination);
-                            removedDirectories.push('Web Contents');
+                            removedDirectories.push(mapping.destination);
+                        }
+                        // The Server settings the environment owns are never taken from the
+                        // archive and must survive the replacement, so carry each one that is
+                        // actually deployed across the directory swap.
+                        if (stagedArtifact && mapping.role === 'server' && workspace) {
+                            for (const name of excludedCopyNames(mapping)) {
+                                if (await exists(path.join(destination, name)))
+                                    preserved.push({ directory: destination, name, source: path.join(workspace, 'preserved', module, name) });
+                            }
+                        }
+                        if (stagedArtifact)
+                            copies.push({ source: path.join(stagedArtifact.expanded, ...mapping.source.split('/')), destination, exclude: [...excludedCopyNames(mapping), ...(mapping.exclude ?? []).map(name => name.toLowerCase())] });
+                        copiedDirectories.push(mapping.destination);
+                        if (mapping.role === 'resource')
+                            continue;
+                        // A native out-of-process service has no assembly and is declared as an
+                        // empty node: the Server loads it from that entry and supplies the rest.
+                        if (mapping.role === 'service') {
+                            if (mapping.service)
+                                entries.push({ destination: mapping.destination, assemblies: [], path: mapping.destination, role: 'service', service: mapping.service });
+                            continue;
+                        }
+                        const assembly = stagedArtifact?.assemblies.get(mapping.destination) ?? knownAssembly(configured, mapping, this.platform);
+                        // Plugins stay relative to the environment root; a worker entry does too,
+                        // and its service keeps using the deployed destination as working directory.
+                        // The Server service the Monitor starts is kept in step the same way.
+                        if (mapping.role === 'plugin' || mapping.role === 'worker' || mapping.role === 'server') {
+                            const entry = { destination: mapping.destination, assemblies: mapping.assemblies, path: path.posix.join(mapping.destination, assembly) };
+                            if (mapping.role === 'worker' || mapping.role === 'server') {
+                                entry.role = mapping.role;
+                                if (mapping.service)
+                                    entry.service = mapping.service;
+                            }
+                            entries.push(entry);
+                        }
+                        // The Monitor resolves its configuration from its own working directory,
+                        // so its package assets belong in the canonical `conf` and the directory
+                        // itself has to point back at it once the Monitor tree is replaced.
+                        if (mapping.role === 'monitor' && stagedArtifact) {
+                            const assets = path.join(stagedArtifact.expanded, 'conf');
+                            if ((await fs.lstat(assets).catch(() => undefined))?.isDirectory())
+                                configurationAssets = { source: assets, destination: path.join(entry.root, 'conf') };
+                            configurationLink = path.join(destination, 'conf');
                         }
-                        copies.push({ source: contents, destination, exclude: [] });
-                        copiedDirectories.push('Web Contents');
                     }
+                    if (module === 'dashboard' && stagedArtifact) {
+                        const contents = path.join(stagedArtifact.expanded, 'Web Contents');
+                        if ((await fs.lstat(contents).catch(() => undefined))?.isDirectory()) {
+                            const destination = path.join(entry.root, 'Web Contents');
+                            if (await exists(destination)) {
+                                removals.push(destination);
+                                removedDirectories.push('Web Contents');
+                            }
+                            copies.push({ source: contents, destination, exclude: [] });
+                            copiedDirectories.push('Web Contents');
+                        }
+                    }
+                    plans.push({
+                        module, previous, next: { version: remoteArtifact.version }, artifact: remoteArtifact, staged: stagedArtifact,
+                        entries, copies, removals, preserved, ...(configurationAssets ? { configurationAssets } : {}), ...(configurationLink ? { configurationLink } : {}),
+                        copiedDirectories, removedDirectories,
+                    });
                 }
-                plans.push({
-                    module, previous, next: { version: remoteArtifact.version }, artifact: remoteArtifact, staged: stagedArtifact,
-                    entries, copies, removals, preserved, ...(configurationAssets ? { configurationAssets } : {}), ...(configurationLink ? { configurationLink } : {}),
-                    copiedDirectories, removedDirectories,
-                });
-            }
-            const changes = plans.map(plan => ({ module: plan.module, previous: plan.previous, next: plan.next, copiedDirectories: plan.copiedDirectories, removedDirectories: plan.removedDirectories }));
-            const configuration = patchEnvironmentConfiguration(configured, plans.flatMap(plan => plan.entries), this.platform);
-            const nextArtifacts = [...artifacts];
-            const nextDownloads = [...downloads];
-            for (const plan of plans) {
-                if (plan.artifact) {
-                    const replacement = {
-                        module: plan.module, plugin: plan.artifact.plugin, version: plan.artifact.version, name: plan.artifact.name, path: plan.artifact.path,
-                        mappings: plan.artifact.mappings.map(mapping => ({ ...mapping, assemblies: [...mapping.assemblies] })),
-                    };
-                    const index = nextArtifacts.findIndex(candidate => candidate.module === plan.module);
-                    if (index < 0)
-                        nextArtifacts.push(replacement);
-                    else
-                        nextArtifacts[index] = { ...nextArtifacts[index], ...replacement };
-                    if (plan.staged) {
-                        const download = { plugin: plan.artifact.plugin, version: plan.artifact.version, name: plan.artifact.name, sha256: plan.staged.sha256 };
-                        const downloadIndex = nextDownloads.findIndex(candidate => candidate.plugin === plan.artifact.plugin);
-                        if (downloadIndex < 0)
-                            nextDownloads.push(download);
+                const changes = plans.map(plan => ({ module: plan.module, previous: plan.previous, next: plan.next, copiedDirectories: plan.copiedDirectories, removedDirectories: plan.removedDirectories }));
+                const configuration = patchEnvironmentConfiguration(configured, plans.flatMap(plan => plan.entries), this.platform);
+                const nextArtifacts = [...artifacts];
+                const nextDownloads = [...downloads];
+                for (const plan of plans) {
+                    if (plan.artifact) {
+                        const replacement = {
+                            module: plan.module, plugin: plan.artifact.plugin, version: plan.artifact.version, name: plan.artifact.name, path: plan.artifact.path,
+                            mappings: plan.artifact.mappings.map(mapping => ({ ...mapping, assemblies: [...mapping.assemblies] })),
+                        };
+                        const index = nextArtifacts.findIndex(candidate => candidate.module === plan.module);
+                        if (index < 0)
+                            nextArtifacts.push(replacement);
                         else
-                            nextDownloads[downloadIndex] = download;
-                        // The requirements the old artifact needed are gone with it: re-read
-                        // the ones the new package actually declares, per deployed mapping.
-                        // A resource mapping is a static tree: it declares none.
-                        requirements = requirements.filter(line => !line.endsWith(` (${plan.module})`));
-                        for (const mapping of plan.staged.layout) {
-                            if (mapping.role === 'service' || mapping.role === 'resource')
-                                continue;
-                            for (const framework of await (0, builder_1.runtimeRequirements)(path.join(plan.staged.expanded, ...mapping.source.split('/')))) {
-                                requirements.push(`${framework.name} ${framework.version} (${plan.module})`);
+                            nextArtifacts[index] = { ...nextArtifacts[index], ...replacement };
+                        if (plan.staged) {
+                            const download = { plugin: plan.artifact.plugin, version: plan.artifact.version, name: plan.artifact.name, sha256: plan.staged.sha256 };
+                            const downloadIndex = nextDownloads.findIndex(candidate => candidate.plugin === plan.artifact.plugin);
+                            if (downloadIndex < 0)
+                                nextDownloads.push(download);
+                            else
+                                nextDownloads[downloadIndex] = download;
+                            // The requirements the old artifact needed are gone with it: re-read
+                            // the ones the new package actually declares, per deployed mapping.
+                            // A resource mapping is a static tree: it declares none.
+                            requirements = requirements.filter(line => !line.endsWith(` (${plan.module})`));
+                            for (const mapping of plan.staged.layout) {
+                                if (mapping.role === 'service' || mapping.role === 'resource')
+                                    continue;
+                                for (const framework of await (0, builder_1.runtimeRequirements)(path.join(plan.staged.expanded, ...mapping.source.split('/')))) {
+                                    requirements.push(`${framework.name} ${framework.version} (${plan.module})`);
+                                }
                             }
                         }
+                        delete moduleSources[plan.module];
                     }
-                    delete moduleSources[plan.module];
-                }
-                if (plan.replacement) {
-                    // The record keeps the public label, the resolved version and the
-                    // payload's SHA256. No remote path and no mapping are written: both
-                    // would expose a name the module hides.
-                    const label = (0, catalog_1.moduleLabel)(catalog_1.catalog[plan.module]);
-                    const replacement = { module: plan.module, plugin: label, version: plan.replacement.version, name: label };
-                    const index = nextArtifacts.findIndex(candidate => candidate.module === plan.module);
-                    if (index < 0)
-                        nextArtifacts.push(replacement);
-                    else
-                        nextArtifacts[index] = { ...nextArtifacts[index], ...replacement };
-                    for (const file of plan.replacement.files) {
-                        const download = { plugin: label, version: plan.replacement.version, name: label, sha256: file.sha256 };
-                        const downloadIndex = nextDownloads.findIndex(candidate => candidate.plugin === label);
-                        if (downloadIndex < 0)
-                            nextDownloads.push(download);
+                    if (plan.replacement) {
+                        // The record keeps the public label, the resolved version and the
+                        // payload's SHA256. No remote path and no mapping are written: both
+                        // would expose a name the module hides.
+                        const label = (0, catalog_1.moduleLabel)(catalog_1.catalog[plan.module]);
+                        const replacement = { module: plan.module, plugin: label, version: plan.replacement.version, name: label };
+                        const index = nextArtifacts.findIndex(candidate => candidate.module === plan.module);
+                        if (index < 0)
+                            nextArtifacts.push(replacement);
                         else
-                            nextDownloads[downloadIndex] = download;
+                            nextArtifacts[index] = { ...nextArtifacts[index], ...replacement };
+                        for (const file of plan.replacement.files) {
+                            const download = { plugin: label, version: plan.replacement.version, name: label, sha256: file.sha256 };
+                            const downloadIndex = nextDownloads.findIndex(candidate => candidate.plugin === label);
+                            if (downloadIndex < 0)
+                                nextDownloads.push(download);
+                            else
+                                nextDownloads[downloadIndex] = download;
+                        }
+                        requirements = requirements.filter(line => !line.endsWith(` (${plan.module})`));
+                        delete moduleSources[plan.module];
                     }
-                    requirements = requirements.filter(line => !line.endsWith(` (${plan.module})`));
-                    delete moduleSources[plan.module];
-                }
-                if (plan.local)
-                    moduleSources[plan.module] = manifestSource(plan.module, plan.local, moduleSources[plan.module]);
-                // First installing a module records it the way `create-env` would: a
-                // selectable one joins the selection, a core component or an automatic
-                // dependency joins the automatically added list instead.
-                if (!installed.has(plan.module)) {
-                    if (selectable.has(plan.module)) {
-                        if (selectedModules)
-                            selectedModules.push(plan.module);
+                    if (plan.local)
+                        moduleSources[plan.module] = manifestSource(plan.module, plan.local, moduleSources[plan.module]);
+                    // First installing a module records it the way `create-env` would: a
+                    // selectable one joins the selection, a core component or an automatic
+                    // dependency joins the automatically added list instead.
+                    if (!installed.has(plan.module)) {
+                        if (selectable.has(plan.module)) {
+                            if (selectedModules)
+                                selectedModules.push(plan.module);
+                        }
+                        else if (autoAddedModules)
+                            autoAddedModules.push(plan.module);
                     }
-                    else if (autoAddedModules)
-                        autoAddedModules.push(plan.module);
                 }
-            }
-            if (selectedModules) {
-                const unique = [...new Set(selectedModules)].sort();
-                selectedModules.length = 0;
-                selectedModules.push(...unique);
-            }
-            if (autoAddedModules) {
-                const unique = [...new Set(autoAddedModules)].sort();
-                autoAddedModules.length = 0;
-                autoAddedModules.push(...unique);
-            }
-            // A create-only module deploys its payload inside the Server directory and is
-            // never refreshed, so a Server refresh replaces the tree it owns: the module
-            // is gone from the environment, and its record goes with it — the manifest
-            // and the registry would otherwise keep claiming a deployment that is not
-            // there any more.
-            const removedCreateOnly = [];
-            if (plans.some(plan => plan.module === 'server')) {
-                for (const module of Object.keys(catalog_1.catalog)) {
-                    if (catalog_1.catalog[module].createOnly !== true || !installed.has(module) || plans.some(plan => plan.module === module))
-                        continue;
-                    const plugin = catalog_1.catalog[module].plugin;
-                    for (let index = nextArtifacts.length - 1; index >= 0; index -= 1)
-                        if (nextArtifacts[index].module === module)
-                            nextArtifacts.splice(index, 1);
-                    for (let index = nextDownloads.length - 1; index >= 0; index -= 1)
-                        if (nextDownloads[index].plugin === plugin)
-                            nextDownloads.splice(index, 1);
-                    for (let index = requirements.length - 1; index >= 0; index -= 1)
-                        if (requirements[index].endsWith(` (${module})`))
-                            requirements.splice(index, 1);
-                    if (autoAddedModules)
-                        autoAddedModules.splice(0, autoAddedModules.length, ...autoAddedModules.filter(name => name !== module));
-                    delete moduleSources[module];
-                    removedCreateOnly.push(module);
+                if (selectedModules) {
+                    const unique = [...new Set(selectedModules)].sort();
+                    selectedModules.length = 0;
+                    selectedModules.push(...unique);
                 }
-            }
-            const nextManifest = { ...manifest, artifacts: nextArtifacts, downloads: nextDownloads, requirements: [...new Set(requirements)] };
-            if (autoAddedModules)
-                nextManifest.autoAddedModules = autoAddedModules;
-            if (Object.keys(moduleSources).length)
-                nextManifest.moduleSources = moduleSources;
-            else
-                delete nextManifest.moduleSources;
-            if (selectedModules)
-                nextManifest.selectedModules = selectedModules;
-            // A stale `resources` key from an older manifest is dropped here: the
-            // packaged-resource feature is gone and nothing records it any more.
-            delete nextManifest.resources;
-            const modules = [...new Set([...entry.modules, ...plans.filter(plan => !installed.has(plan.module) && selectable.has(plan.module)).map(plan => plan.module)])].filter(module => !removedCreateOnly.includes(module)).sort();
-            const localModules = Object.keys(moduleSources).sort();
-            if (state === 'running')
-                warnings.push(`${entry.name} is running; restart it to load the updated modules.`);
-            for (const item of skipped) {
-                if (item.reason === 'local')
-                    warnings.push(`${item.module} has a local source and was not updated from artifacts.`);
-                else if (item.reason === 'provider')
-                    warnings.push(`${item.module} is published only on ${(0, catalog_1.providerLabel)('oss')} and was not updated from ${(0, catalog_1.providerLabel)('az')}.`);
-            }
-            const currentSkipped = skipped.filter(item => item.reason === 'current');
-            if (currentSkipped.length)
-                warnings.push(`Already at the resolved version (nothing updated): ${currentSkipped.map(item => `${item.module} ${current.get(item.module)}`).join(', ')}.`);
-            // The Server and Monitor packages each ship the XSD assets for a
-            // configuration schema, so replacing one of them alone leaves the
-            // environment mixing two package generations for the same configuration.
-            // Only a plan that really deployed a package pairs with the other package;
-            // recording a local Server build directory touches no package at all.
-            const runtime = plans.filter(plan => (plan.module === 'server' || plan.module === 'monitoring') && plan.copiedDirectories.length > 0).map(plan => plan.module).sort();
-            if (runtime.length === 1)
-                warnings.push(`Only ${runtime[0]} was refreshed; refresh ${runtime[0] === 'server' ? 'monitoring' : 'server'} in the same call to keep both packages on one configuration schema.`);
-            if (parsed.some(spec => spec.module === 'documents') && !parsed.some(spec => spec.module === 'collaboration')) {
-                warnings.push('documents was refreshed without collaboration; the smart documents plugin may expect the deployed collaboration service version, so refresh collaboration too.');
-            }
-            if (autoRefreshed.length)
-                warnings.push(`${autoRefreshed.join(', ')} was refreshed with the Server package: its trees live inside the Server directory and would otherwise be lost.`);
-            if (autoReplaced.length)
-                warnings.push(`${autoReplaced.join(', ')} was re-applied with the Server package: the new package ships the file it replaces, so it was applied again.`);
-            if (removedCreateOnly.length)
-                warnings.push(`${removedCreateOnly.join(', ')} was removed with the Server package: it is deployed only when an environment is created.`);
-            // Nothing to deploy: every requested module is already at the resolved
-            // version with a complete deployment. Do not rewrite the manifest, the
-            // registry or the configuration just to say so.
-            if (!plans.length) {
-                onProgress?.(`${entry.name}: nothing to update; every requested module is already at its resolved version`);
-                return { name: entry.name, root: entry.root, dryRun, changes, skipped, restartRequired: false, warnings, localTargets: [] };
-            }
-            if (!dryRun) {
-                for (const plan of plans) {
-                    // Take the environment-owned settings aside first, and drop the Monitor
-                    // configuration junction before the directory holding it: a recursive
-                    // delete must never reach the canonical `conf` the junction points at.
-                    for (const file of plan.preserved) {
-                        await fs.mkdir(path.dirname(file.source), { recursive: true });
-                        await fs.copyFile(path.join(file.directory, file.name), file.source);
-                    }
-                    if (plan.configurationLink) {
-                        const existing = await fs.lstat(plan.configurationLink).catch(() => undefined);
-                        if (existing?.isSymbolicLink())
-                            await fs.unlink(plan.configurationLink);
-                        else
-                            await fs.rm(plan.configurationLink, { recursive: true, force: true });
+                if (autoAddedModules) {
+                    const unique = [...new Set(autoAddedModules)].sort();
+                    autoAddedModules.length = 0;
+                    autoAddedModules.push(...unique);
+                }
+                // A create-only module deploys its payload inside the Server directory and is
+                // never refreshed, so a Server refresh replaces the tree it owns: the module
+                // is gone from the environment, and its record goes with it — the manifest
+                // and the registry would otherwise keep claiming a deployment that is not
+                // there any more.
+                const removedCreateOnly = [];
+                if (plans.some(plan => plan.module === 'server')) {
+                    for (const module of Object.keys(catalog_1.catalog)) {
+                        if (catalog_1.catalog[module].createOnly !== true || !installed.has(module) || plans.some(plan => plan.module === module))
+                            continue;
+                        const plugin = catalog_1.catalog[module].plugin;
+                        for (let index = nextArtifacts.length - 1; index >= 0; index -= 1)
+                            if (nextArtifacts[index].module === module)
+                                nextArtifacts.splice(index, 1);
+                        for (let index = nextDownloads.length - 1; index >= 0; index -= 1)
+                            if (nextDownloads[index].plugin === plugin)
+                                nextDownloads.splice(index, 1);
+                        for (let index = requirements.length - 1; index >= 0; index -= 1)
+                            if (requirements[index].endsWith(` (${module})`))
+                                requirements.splice(index, 1);
+                        if (autoAddedModules)
+                            autoAddedModules.splice(0, autoAddedModules.length, ...autoAddedModules.filter(name => name !== module));
+                        delete moduleSources[module];
+                        removedCreateOnly.push(module);
                     }
-                    for (const removal of plan.removals)
-                        await fs.rm(removal, { recursive: true, force: true });
-                    for (const copy of plan.copies)
-                        await (0, builder_1.copyTree)(copy.source, copy.destination, copy.exclude);
-                    for (const file of plan.preserved)
-                        await fs.copyFile(file.source, path.join(file.directory, file.name));
-                    // The replacement is applied after the directory it lives in has been
-                    // copied, so a Server refresh cannot overwrite it again. The target is
-                    // re-checked here and every error names the module only.
-                    if (plan.replacement) {
-                        const label = (0, catalog_1.moduleLabel)(catalog_1.catalog[plan.module]);
-                        try {
-                            for (const file of plan.replacement.files) {
-                                const stat = await fs.lstat(file.destination).catch(() => undefined);
-                                if (!stat)
-                                    throw new Error('missing');
-                                if (!stat.isFile() || stat.isSymbolicLink())
-                                    throw new Error('not a regular file');
-                                await fs.copyFile(file.source, file.destination);
+                }
+                const nextManifest = { ...manifest, artifacts: nextArtifacts, downloads: nextDownloads, requirements: [...new Set(requirements)] };
+                if (autoAddedModules)
+                    nextManifest.autoAddedModules = autoAddedModules;
+                if (Object.keys(moduleSources).length)
+                    nextManifest.moduleSources = moduleSources;
+                else
+                    delete nextManifest.moduleSources;
+                if (selectedModules)
+                    nextManifest.selectedModules = selectedModules;
+                // A stale `resources` key from an older manifest is dropped here: the
+                // packaged-resource feature is gone and nothing records it any more.
+                delete nextManifest.resources;
+                const modules = [...new Set([...entry.modules, ...plans.filter(plan => !installed.has(plan.module) && selectable.has(plan.module)).map(plan => plan.module)])].filter(module => !removedCreateOnly.includes(module)).sort();
+                const localModules = Object.keys(moduleSources).sort();
+                if (state === 'running')
+                    warnings.push(`${entry.name} is running; restart it to load the updated modules.`);
+                for (const item of skipped) {
+                    if (item.reason === 'local')
+                        warnings.push(`${item.module} has a local source and was not updated from artifacts.`);
+                    else if (item.reason === 'provider')
+                        warnings.push(`${item.module} is published only on ${(0, catalog_1.providerLabel)('oss')} and was not updated from ${(0, catalog_1.providerLabel)('az')}.`);
+                }
+                const currentSkipped = skipped.filter(item => item.reason === 'current');
+                if (currentSkipped.length)
+                    warnings.push(`Already at the resolved version (nothing updated): ${currentSkipped.map(item => `${item.module} ${current.get(item.module)}`).join(', ')}.`);
+                // The Server and Monitor packages each ship the XSD assets for a
+                // configuration schema, so replacing one of them alone leaves the
+                // environment mixing two package generations for the same configuration.
+                // Only a plan that really deployed a package pairs with the other package;
+                // recording a local Server build directory touches no package at all.
+                const runtime = plans.filter(plan => (plan.module === 'server' || plan.module === 'monitoring') && plan.copiedDirectories.length > 0).map(plan => plan.module).sort();
+                if (runtime.length === 1)
+                    warnings.push(`Only ${runtime[0]} was refreshed; refresh ${runtime[0] === 'server' ? 'monitoring' : 'server'} in the same call to keep both packages on one configuration schema.`);
+                if (parsed.some(spec => spec.module === 'documents') && !parsed.some(spec => spec.module === 'collaboration')) {
+                    warnings.push('documents was refreshed without collaboration; the smart documents plugin may expect the deployed collaboration service version, so refresh collaboration too.');
+                }
+                if (autoRefreshed.length)
+                    warnings.push(`${autoRefreshed.join(', ')} was refreshed with the Server package: its trees live inside the Server directory and would otherwise be lost.`);
+                if (autoReplaced.length)
+                    warnings.push(`${autoReplaced.join(', ')} was re-applied with the Server package: the new package ships the file it replaces, so it was applied again.`);
+                if (removedCreateOnly.length)
+                    warnings.push(`${removedCreateOnly.join(', ')} was removed with the Server package: it is deployed only when an environment is created.`);
+                // Nothing to deploy: every requested module is already at the resolved
+                // version with a complete deployment. Do not rewrite the manifest, the
+                // registry or the configuration just to say so.
+                if (!plans.length) {
+                    onProgress?.(`${entry.name}: nothing to update; every requested module is already at its resolved version`);
+                    return { name: entry.name, root: entry.root, dryRun, changes, skipped, restartRequired: false, warnings, localTargets: [] };
+                }
+                if (!dryRun) {
+                    for (const plan of plans) {
+                        // Take the environment-owned settings aside first, and drop the Monitor
+                        // configuration junction before the directory holding it: a recursive
+                        // delete must never reach the canonical `conf` the junction points at.
+                        for (const file of plan.preserved) {
+                            await fs.mkdir(path.dirname(file.source), { recursive: true });
+                            await fs.copyFile(path.join(file.directory, file.name), file.source);
+                        }
+                        if (plan.configurationLink) {
+                            const existing = await fs.lstat(plan.configurationLink).catch(() => undefined);
+                            if (existing?.isSymbolicLink())
+                                await fs.unlink(plan.configurationLink);
+                            else
+                                await fs.rm(plan.configurationLink, { recursive: true, force: true });
+                        }
+                        for (const removal of plan.removals)
+                            await fs.rm(removal, { recursive: true, force: true });
+                        for (const copy of plan.copies)
+                            await (0, builder_1.copyTree)(copy.source, copy.destination, copy.exclude);
+                        for (const file of plan.preserved)
+                            await fs.copyFile(file.source, path.join(file.directory, file.name));
+                        // The replacement is applied after the directory it lives in has been
+                        // copied, so a Server refresh cannot overwrite it again. The target is
+                        // re-checked here and every error names the module only.
+                        if (plan.replacement) {
+                            const label = (0, catalog_1.moduleLabel)(catalog_1.catalog[plan.module]);
+                            try {
+                                for (const file of plan.replacement.files) {
+                                    const stat = await fs.lstat(file.destination).catch(() => undefined);
+                                    if (!stat)
+                                        throw new Error('missing');
+                                    if (!stat.isFile() || stat.isSymbolicLink())
+                                        throw new Error('not a regular file');
+                                    await fs.copyFile(file.source, file.destination);
+                                }
+                            }
+                            catch {
+                                throw new Error(`Module ${label} could not be applied: the Server tree holds no regular file to replace.`);
                             }
                         }
-                        catch {
-                            throw new Error(`Module ${label} could not be applied: the Server tree holds no regular file to replace.`);
+                        if (plan.configurationAssets) {
+                            onProgress?.(`Refreshing Monitor configuration assets in ${path.relative(entry.root, plan.configurationAssets.destination)}`);
+                            await mergeConfigurationAssets(plan.configurationAssets.source, plan.configurationAssets.destination);
                         }
+                        if (plan.configurationLink)
+                            await fs.symlink(path.join(entry.root, 'conf'), plan.configurationLink, 'junction');
                     }
-                    if (plan.configurationAssets) {
-                        onProgress?.(`Refreshing Monitor configuration assets in ${path.relative(entry.root, plan.configurationAssets.destination)}`);
-                        await mergeConfigurationAssets(plan.configurationAssets.source, plan.configurationAssets.destination);
-                    }
-                    if (plan.configurationLink)
-                        await fs.symlink(path.join(entry.root, 'conf'), plan.configurationLink, 'junction');
+                    // Only a plan that really contributes something to the configuration
+                    // rewrites it: a module that adds no plugin, worker or service entry
+                    // leaves `conf/Wyn.conf` exactly as it is instead of round-tripping it
+                    // through the XML builder. (The built-in modules are create-only, so an
+                    // update never plans one.)
+                    const configurationChanged = plans.some(plan => plan.entries.length > 0 || plan.configurationAssets !== undefined || plan.configurationLink !== undefined);
+                    onProgress?.(configurationChanged ? 'Writing configuration, manifest and registry record' : 'Writing manifest and registry record');
+                    if (configurationChanged)
+                        await writeAtomic(path.join(entry.root, 'conf', 'Wyn.conf'), configuration);
+                    await writeJsonAtomic(path.join(entry.root, 'environment.lock.json'), nextManifest);
+                    await this.registry.update(entries => {
+                        const index = entries.findIndex(candidate => candidate.id === entry.id);
+                        if (index < 0)
+                            throw new Error('Environment record disappeared during update.');
+                        if (entries[index].root !== entry.root)
+                            throw new Error('Environment changed during update.');
+                        entries[index].modules = modules;
+                        if (localModules.length)
+                            entries[index].localModules = localModules;
+                        else
+                            delete entries[index].localModules;
+                    });
                 }
-                // Only a plan that really contributes something to the configuration
-                // rewrites it: a module that adds no plugin, worker or service entry
-                // leaves `conf/Wyn.conf` exactly as it is instead of round-tripping it
-                // through the XML builder. (The built-in modules are create-only, so an
-                // update never plans one.)
-                const configurationChanged = plans.some(plan => plan.entries.length > 0 || plan.configurationAssets !== undefined || plan.configurationLink !== undefined);
-                onProgress?.(configurationChanged ? 'Writing configuration, manifest and registry record' : 'Writing manifest and registry record');
-                if (configurationChanged)
-                    await writeAtomic(path.join(entry.root, 'conf', 'Wyn.conf'), configuration);
-                await writeJsonAtomic(path.join(entry.root, 'environment.lock.json'), nextManifest);
-                await this.registry.update(entries => {
-                    const index = entries.findIndex(candidate => candidate.id === entry.id);
-                    if (index < 0)
-                        throw new Error('Environment record disappeared during update.');
-                    if (entries[index].root !== entry.root)
-                        throw new Error('Environment changed during update.');
-                    entries[index].modules = modules;
-                    if (localModules.length)
-                        entries[index].localModules = localModules;
-                    else
-                        delete entries[index].localModules;
-                });
+                const restartRequired = !dryRun && changes.length > 0;
+                if (restartRequired)
+                    onProgress?.(`${entry.name}: modules updated; restart the environment to load the change (no service was started).`);
+                return { name: entry.name, root: entry.root, dryRun, changes, skipped, restartRequired, warnings, localTargets: plans.flatMap(plan => plan.local ?? []) };
             }
-            const restartRequired = !dryRun && changes.length > 0;
-            if (restartRequired)
-                onProgress?.(`${entry.name}: modules updated; restart the environment to load the change (no service was started).`);
-            return { name: entry.name, root: entry.root, dryRun, changes, skipped, restartRequired, warnings, localTargets: plans.flatMap(plan => plan.local ?? []) };
-        }
-        finally {
-            if (workspace)
-                await fs.rm(workspace, { recursive: true, force: true });
-        }
+            finally {
+                if (workspace)
+                    await fs.rm(workspace, { recursive: true, force: true });
+            }
+        });
     }
 }
 exports.EnvironmentUpdater = EnvironmentUpdater;