@harperfast/harper 5.3.0-alpha.1 → 5.3.0-beta.1

package/components/operations.js

@@ -2,6 +2,7 @@
 
 const path = require('node:path');
 const { isMainThread, parentPort } = require('node:worker_threads');
+const { isDeepStrictEqual } = require('node:util');
 const fs = require('fs-extra');
 const fg = require('fast-glob');
 const normalize = require('normalize-path');
@@ -48,6 +49,7 @@ const {
 const { ProgressEmitter } = require('../server/serverHelpers/progressEmitter.ts');
 
 const DROP_COMPONENT_LOCK_TIMEOUT_MS = 5 * 60 * 1000;
+const ISOLATED_TOPOLOGY_REQUEST_TIMEOUT_MS = 5000;
 
 function componentDropLockOptions(project) {
 	return {
@@ -588,13 +590,67 @@ async function deployComponent(req) {
 	// replicated ciphertext (reference, not embed); already-reference entries pass through, and with
 	// no custody a literal token stays as a transient, this-node-only fallback (#1158). Peers
 	// re-running a replicated deploy already carry references and never re-ingest.
+	const { isIsolatedApplication } = require('../server/threads/isolatedApplications.ts');
+	const requestedIsolation = req.isolated;
+	const isReplicatedExecution = typeof req._deploymentId === 'string';
+	const mode = req.deployment_id ? 'activate' : req.activate === false ? 'stage' : 'deploy';
+	const isActivation = mode === 'activate';
+	// this thread's cached config may predate an earlier deploy that changed the entry without a restart
+	env.initSync(true);
+	const initiallyIsolated = isIsolatedApplication(req.project);
+	if (requestedIsolation !== undefined && !req.package) {
+		throw handleHDBError(
+			new Error(),
+			`'isolated' is only supported for package deployments; set it on the application's root config entry instead`,
+			HTTP_STATUS_CODES.BAD_REQUEST
+		);
+	}
+	// Only the originating node rejects admission: replicated peers must commit the same desired config,
+	// then report any node-local inability to run it through component lifecycle status.
+	const assertIsolationAdmission = async (isolated) => {
+		if (!isolated || isReplicatedExecution) return;
+		const {
+			isolatedApplicationRefusal,
+			isolatedApplicationCapacityRefusal,
+			presentIsolatedApplicationNames,
+		} = require('../server/threads/isolatedApplications.ts');
+		let runningApplications;
+		try {
+			runningApplications = await manageThreads.getRunningIsolatedApplications(ISOLATED_TOPOLOGY_REQUEST_TIMEOUT_MS);
+		} catch (error) {
+			throw handleHDBError(
+				error,
+				`Cannot deploy '${req.project}' as an isolated application: the main thread's worker topology is unavailable: ${error.message}`,
+				HTTP_STATUS_CODES.SERVICE_UNAVAILABLE
+			);
+		}
+		runningApplications = new Set([
+			...runningApplications,
+			...presentIsolatedApplicationNames().filter((application) => !isolatedApplicationRefusal(application)),
+		]);
+		const refusal =
+			isolatedApplicationRefusal(req.project) ?? isolatedApplicationCapacityRefusal(req.project, runningApplications);
+		if (refusal) {
+			throw handleHDBError(
+				new Error(),
+				`Cannot deploy '${req.project}' as an isolated application: ${refusal}`,
+				HTTP_STATUS_CODES.CONFLICT
+			);
+		}
+	};
+	// Skipped for an activation: the artifact's descriptor is the authority for the isolation it wants, and
+	// `admitIsolation` runs the real check under the preparation lock. Admitting the CURRENT value here would
+	// refuse an activation whose artifact turns isolation OFF for a component whose present isolated state is
+	// itself the refusal — a 409 for the request that would fix it.
+	if (!isActivation) await assertIsolationAdmission(requestedIsolation ?? initiallyIsolated);
 	const { ingestCredentials, resolveCredentials } = require('./secretOperations.ts');
-	req.credentials = await ingestCredentials(req, req.credentials, req.project);
+	// An activation resolves, fetches and installs nothing, so there is no credential for it to carry.
+	// The validator rejects one; this keeps the ingest itself off the path rather than relying on that.
+	if (!isActivation) req.credentials = await ingestCredentials(req, req.credentials, req.project);
 	// References are safe to persist (config + deployment row) and replicate; a no-custody literal
 	// token is not — it is used only for this node's install below, then stripped before replication.
 	const credentialReferences = (req.credentials ?? []).filter((entry) => entry && entry.secret !== undefined);
 
-	// Write to root config if the request contains a package identifier
 	if (req.package) {
 		// Check if trying to overwrite a core component (requires force)
 		// Lazy-load to avoid circular dependency with componentLoader
@@ -606,29 +662,9 @@ async function deployComponent(req) {
 				HTTP_STATUS_CODES.CONFLICT
 			);
 		}
-
-		const applicationConfig = { package: req.package };
-		// Avoid writing an empty `install:` block
-		if (req.install_command || req.install_timeout || req.install_allow_scripts !== undefined) {
-			applicationConfig.install = {
-				command: req.install_command,
-				timeout: req.install_timeout,
-				allowInstallScripts: req.install_allow_scripts,
-			};
-		}
-		if (req.urlPath !== undefined) applicationConfig.urlPath = req.urlPath;
-		if (req.host !== undefined) applicationConfig.host = req.host;
-		// Same convention as host/urlPath above, and for the same reason: a package redeploy rebuilds
-		// this application's whole root-config entry from request fields, so a deployment-level key that
-		// isn't re-supplied here is silently dropped -- for branchedDatabases specifically, that means an
-		// application which believed it had a private fork resumes sharing the base after the next
-		// restart, with nothing in this operation to say so.
-		if (req.branchedDatabases !== undefined) applicationConfig.branchedDatabases = req.branchedDatabases;
-		// Persist credential references (never tokens) so every cold install of this component —
-		// reboot, new peer, rollback — re-resolves the credential from the store.
-		if (credentialReferences.length) applicationConfig.credentials = credentialReferences;
-		await configUtils.addConfig(req.project, applicationConfig);
 	}
+	let wasIsolated;
+	let nowIsolated;
 
 	// Create a hdb_deployment row up front so the deploy is observable and auditable
 	// even if the CLI disconnects. The row also holds the payload in a Blob attribute,
@@ -638,7 +674,6 @@ async function deployComponent(req) {
 	// recording so we don't accumulate one row per node for the same deploy. The row
 	// reaches peers via the table's standard replication; the peer-side branch below
 	// reads payload_blob back from there.
-	const isReplicatedExecution = typeof req._deploymentId === 'string';
 	// An SSE-bound caller already attached a ProgressEmitter (created in the server
 	// handler so it can also drive the response stream). Reuse it; otherwise spin up a
 	// fresh emitter so the recorder still gets phase events for non-SSE deploys.
@@ -650,6 +685,7 @@ async function deployComponent(req) {
 				project: req.project,
 				package_identifier: req.package ?? null,
 				user: req.hdb_user?.username,
+				activated_from: req.deployment_id ?? null,
 				restart_mode: req.restart === 'rolling' ? 'rolling' : req.restart ? 'immediate' : null,
 				// Reference form only — the rollback source for re-resolving the credential.
 				credentials: credentialReferences.length ? credentialReferences : null,
@@ -674,12 +710,18 @@ async function deployComponent(req) {
 	// Bounded ring buffer of install stdout/stderr so a non-SSE caller sees the tail
 	// in the thrown error. SSE callers still stream every line live.
 	const installCapture = createInstallCapture();
+	let stagedOnOrigin = false;
 	try {
 		// On the origin, tee the tarball (Buffer or Readable from the multipart parser)
 		// through a hash-and-size tap into the row's payload_blob, then re-source extraction
 		// from the persisted blob. When `system` replicates, the blob becomes the channel
 		// peers read from; when it doesn't, the blob stays local for audit and rollback.
-		if (recorder && req.payload != null) {
+		if (isActivation) {
+			// A replicated activation has exactly the shape the peer-side blob branch below keys on — neither
+			// `package` nor `payload` — so without this branch every peer would wait out `deployment_timeout`
+			// for a payload its row never had while the origin swapped successfully.
+			extractionPayload = undefined;
+		} else if (recorder && req.payload != null) {
 			await recorder.ingestPayload(req.payload);
 			extractionPayload = recorder.row.payload_blob.stream();
 		} else if (isReplicatedExecution && req.payload == null && !req.package) {
@@ -715,9 +757,13 @@ async function deployComponent(req) {
 		if (isReplicatedExecution) {
 			credentialsWaitMs = coerceTimeoutMs(req.deployment_timeout, DEFAULT_AWAIT_ROW_TIMEOUT_MS);
 		}
-		const resolvedCredentials = await resolveCredentials(req.credentials, req.project, {
-			waitMs: credentialsWaitMs,
-		});
+		// Skipped for an activation, which runs no pack, clone or install: waiting for an hdb_secret row to
+		// replicate in would only delay a swap that has nothing to authenticate to.
+		const resolvedCredentials = isActivation
+			? undefined
+			: await resolveCredentials(req.credentials, req.project, {
+					waitMs: credentialsWaitMs,
+				});
 
 		const application = new Application({
 			name: req.project,
@@ -755,12 +801,90 @@ async function deployComponent(req) {
 		// committed" — so a later failure arrives after both phases reported success. The operation's error
 		// is the authority on whether the deploy landed, not the phase stream.
 		emit('phase', { phase: 'prepare', status: 'start' });
+		// The root-config entry a package deploy publishes. A stage records it with the artifact instead of
+		// publishing it, so a staged release nobody activated cannot leave config naming it — and the
+		// activation that eventually publishes it does so in the same order a normal deploy does.
+		let stagedRootConfig = null;
 		await prepareApplication(application, {
+			// `.deploy-staging/<artifactId>`. The public deployment id, so the id the caller was handed is
+			// the id a later `deployment_id` request can name; an activation names the artifact's own id,
+			// not the new row's.
+			artifactId: req.deployment_id ?? req._deploymentId,
+			mode,
+			describeArtifact: () => ({ rootConfig: stagedRootConfig, isolated: Boolean(nowIsolated) }),
+			// Returns its own undo. Publication happens BEFORE the swap, in the same order a normal deploy
+			// uses, so an activation that fails pre-commit would otherwise leave config naming a release that
+			// is not live — and `installApplications()` would resolve and install that package from scratch at
+			// the next boot, over a component whose certified artifact is sitting right there. Restoring is
+			// best-effort and not durable (that is #2315 step 3's work); it is still the difference between a
+			// failed activation that changed nothing and one that re-points the component.
+			publishRootConfig: async (entry) => {
+				const previous = configUtils.getConfigObj()?.[req.project];
+				await configUtils.addConfig(req.project, entry);
+				env.initSync(true);
+				// Read BACK, not `entry` — see `publishedEntryStillStands`.
+				const published = configUtils.getConfigObj()?.[req.project];
+				return async () => {
+					if (
+						!publishedEntryStillStands(
+							published,
+							() => env.initSync(true),
+							() => configUtils.getConfigObj()?.[req.project]
+						)
+					) {
+						return;
+					}
+					if (previous === undefined) configUtils.deleteConfigFromFile([req.project]);
+					else await configUtils.addConfig(req.project, previous);
+					env.initSync(true);
+				};
+			},
+			admitIsolation: async (descriptor) => {
+				env.initSync(true);
+				wasIsolated = isIsolatedApplication(req.project);
+				// A package artifact restores its own root-config entry, so its recorded intent is what will
+				// be in force. A payload artifact publishes no config, so the effective configuration is the
+				// only authority there — a saved `false` must not admit past an isolation the operator set
+				// between the stage and this call.
+				nowIsolated = descriptor.rootConfig ? descriptor.isolated : wasIsolated;
+				await assertIsolationAdmission(nowIsolated);
+			},
+			beforePrepare: async () => {
+				if (isActivation) return;
+				env.initSync(true);
+				wasIsolated = isIsolatedApplication(req.project);
+				nowIsolated = requestedIsolation ?? wasIsolated;
+				await assertIsolationAdmission(nowIsolated);
+				if (!isReplicatedExecution && req.package) req.isolated = nowIsolated;
+				if (!req.package) return;
+				const applicationConfig = { package: req.package };
+				if (req.install_command || req.install_timeout || req.install_allow_scripts !== undefined) {
+					applicationConfig.install = {
+						command: req.install_command,
+						timeout: req.install_timeout,
+						allowInstallScripts: req.install_allow_scripts,
+					};
+				}
+				if (req.urlPath !== undefined) applicationConfig.urlPath = req.urlPath;
+				if (req.host !== undefined) applicationConfig.host = req.host;
+				if (req.branchedDatabases !== undefined) applicationConfig.branchedDatabases = req.branchedDatabases;
+				if (nowIsolated) applicationConfig.isolated = true;
+				if (credentialReferences.length) applicationConfig.credentials = credentialReferences;
+				if (mode === 'stage') {
+					stagedRootConfig = applicationConfig;
+					return;
+				}
+				await configUtils.addConfig(req.project, applicationConfig);
+				env.initSync(true);
+			},
 			validateCandidate: async (candidateDirPath) => {
 				emit('phase', { phase: 'prepare', status: 'done' });
 				await validateComponentLoads(candidateDirPath, emit);
 			},
 		});
+		// The build is certified on disk from here on, so every later failure — a peer result, or a rejection
+		// thrown by the replication layer itself — still leaves an artifact this id can activate.
+		if (mode === 'stage') stagedOnOrigin = true;
 		const rollingRestart = req.restart === 'rolling';
 		// if doing a rolling restart set restart to false so that other nodes don't also restart.
 		req.restart = rollingRestart ? false : req.restart;
@@ -803,7 +927,18 @@ async function deployComponent(req) {
 			// when the per-peer callback already fired for these.
 			recorder.recordPeers(response.replicated);
 		}
-		if (req.restart === true) {
+		// A still-isolated application restarts only its own dedicated worker. Everything else restarts the
+		// pool: a shared application, and either direction of an isolation flip, where the reconcile in
+		// restartWorkers starts or stops the moving application's own worker.
+		const restartScope = wasIsolated && nowIsolated ? application.name : undefined;
+		if (mode === 'stage') {
+			// No restart and no restart-required flag: nothing about the running component changed. The
+			// marker is what tells the origin which peers understood the request — see the confirmation
+			// check below — and it is set on every node, origin included, since a peer returns this same
+			// object as its operation response.
+			response.staged = true;
+			response.message = `Staged: ${application.name}`;
+		} else if (req.restart === true) {
 			emit('phase', { phase: 'restart', status: 'start' });
 			// Workers not yet replaced keep serving the pre-deploy component set, and where the OS lets
 			// replacements share a port they keep accepting connections for the whole rolling restart, so
@@ -811,7 +946,7 @@ async function deployComponent(req) {
 			// never heard of it.
 			const { awaitRestart } = require('./awaitRestart.ts');
 			const restart = await awaitRestart((onProgress) =>
-				manageThreads.restartWorkers('http', undefined, undefined, onProgress)
+				manageThreads.restartWorkers('http', undefined, undefined, onProgress, restartScope)
 			);
 			emit('phase', { phase: 'restart', status: 'done' });
 			logRestartOutcome(restart, `deploying ${application.name}`);
@@ -822,6 +957,8 @@ async function deployComponent(req) {
 			const jobResponse = await serverUtilities.executeJob({
 				operation: 'restart_service',
 				service: 'http',
+				scope: manageThreads.encodeRestartScope(restartScope),
+				scopeFallback: restartScope === undefined ? undefined : manageThreads.encodeRestartScope(undefined),
 				replicated: true,
 			});
 			emit('phase', { phase: 'restart', status: 'done' });
@@ -841,10 +978,13 @@ async function deployComponent(req) {
 			// An existing component's watched files are handled by Scope/EntryHandler. Package
 			// metadata is deliberately outside most plugin globs, so compare it across the atomic
 			// swap as well: a dependency or module-entry change also invalidates loaded code.
-			if (application.isNewComponent || application.packageMetadataChanged) {
-				const { requestRestart } = require('./requestRestart.ts');
-				requestRestart();
-			}
+			const { requestRestartAfterDeploy } = require('./requestRestart.ts');
+			requestRestartAfterDeploy(
+				application.isNewComponent,
+				application.packageMetadataChanged,
+				wasIsolated,
+				nowIsolated
+			);
 			response.message = `Successfully deployed: ${application.name}`;
 		}
 
@@ -860,12 +1000,37 @@ async function deployComponent(req) {
 				const detail = failedPeers
 					.map((peer) => `${peer.node ?? 'unknown'} (${peer.error?.message ?? 'unknown error'})`)
 					.join(', ');
-				throw new ServerError(
-					`Component '${application.name}' was deployed on the origin node but failed to replicate to ` +
-						`${failedPeers.length} of ${recorder.row.peer_results.length} peer node(s): ${detail}. ` +
-						`See deployment ${recorder.deploymentId} (get_deployment) for details, or pass ` +
-						`ignore_replication_errors: true to treat replication failures as non-fatal.`
+				const replicationError = new ServerError(
+					`Component '${application.name}' was ${mode === 'stage' ? 'staged' : 'deployed'} on the origin node ` +
+						`but failed to replicate to ${failedPeers.length} of ${recorder.row.peer_results.length} peer ` +
+						`node(s): ${detail}. See deployment ${recorder.deploymentId} (get_deployment) for details, or ` +
+						`pass ignore_replication_errors: true to treat replication failures as non-fatal.`
 				);
+				throw replicationError;
+			}
+
+			// A peer running a build that predates staged deploys accepts `activate: false` as an unknown
+			// field and performs its ordinary deploy, so it is now serving a release the operator asked only
+			// to stage. Nothing can prevent that — the operations channel carries no peer version or
+			// capability — so the origin reports it, from the one signal that separates the two cases: a node
+			// that staged says so in its response. Read from the raw aggregate, because the recorder's peer
+			// normalization keeps only node/status/error.
+			//
+			// The wording stays at "did not confirm". An unreachable peer and one that dropped the request
+			// look identical from here, and telling an operator those nodes went live would be a guess.
+			if (mode === 'stage') {
+				const unconfirmed = unconfirmedStagingPeers(response?.replicated);
+				if (unconfirmed.length > 0) {
+					const detail = unconfirmed.map((peer) => peer.node ?? 'unknown').join(', ');
+					const unconfirmedError = new ServerError(
+						`Component '${application.name}' was staged on the origin node, but ${unconfirmed.length} peer ` +
+							`node(s) did not confirm staging: ${detail}. Either they are unreachable, or they run a build ` +
+							`that predates staged deploys — which treats this request as an ordinary deploy, so the ` +
+							`release is already serving there. Check those nodes before activating deployment ` +
+							`${recorder.deploymentId}, or pass ignore_replication_errors: true to accept the difference.`
+					);
+					throw unconfirmedError;
+				}
 			}
 		}
 
@@ -879,14 +1044,28 @@ async function deployComponent(req) {
 			// the tarball when it's still the artifact you'd debug or retry with: failed deploys
 			// don't reach this branch, and a deploy that reached here only because
 			// ignore_replication_errors masked failed peers keeps its payload for those peers.
+			// Never for a stage: the artifact on disk is not yet a release anyone can re-derive, and retention
+			// can evict it (it shares `deployment_stagingRetention_maxCount` with incidental dormant builds),
+			// so dropping the tarball here is how a staged release becomes unrecoverable — no tree, no bytes,
+			// and a row still reporting `staged`. An operator can still reclaim it deliberately with
+			// delete_deployment_payload once they accept that.
 			const payloadSize = recorder.row.payload_size;
 			const retentionMaxSize = getPayloadRetentionMaxSize();
-			if (typeof payloadSize === 'number' && payloadSize > retentionMaxSize && recorder.getFailedPeers().length === 0) {
+			if (
+				mode !== 'stage' &&
+				typeof payloadSize === 'number' &&
+				payloadSize > retentionMaxSize &&
+				recorder.getFailedPeers().length === 0
+			) {
 				const freed = recorder.dropPayload();
 				if (freed > 0) emit('payload_dropped', { payload_size: freed, max_size: retentionMaxSize });
 			}
-			emit('phase', { phase: 'success', status: 'done' });
-			await recorder.finish('success');
+			emit('phase', { phase: mode === 'stage' ? 'staged' : 'success', status: 'done' });
+			await recorder.finish(mode === 'stage' ? 'staged' : 'success');
+			if (mode === 'stage') {
+				response.message =
+					`Staged: ${application.name}. Deploy it with deploy_component ` + `deployment_id=${recorder.deploymentId}`;
+			}
 		}
 		return response;
 	} catch (err) {
@@ -927,7 +1106,7 @@ async function deployComponent(req) {
 		// install output, and failed_peers the caller needs.
 		if (recorder) {
 			try {
-				await recorder.finish('failed', err);
+				await recorder.finish(stagedOnOrigin ? 'staged' : 'failed', err);
 			} catch (finishErr) {
 				log.warn('Failed to record deployment failure row', finishErr);
 			}
@@ -936,6 +1115,43 @@ async function deployComponent(req) {
 	}
 }
 
+/**
+ * Whether the root-config entry an activation published is still the one on disk — the condition for that
+ * activation's failure to take it back. A `set_configuration` acknowledged while the swap was retrying is
+ * not this operation's to overwrite, and restoring a snapshot taken before it would silently drop it.
+ *
+ * Split out from the caller so it can be tested without a deploy: this is the only guard on a hazard the
+ * preparation lock does not cover, and both ways it can regress fail silently. `refreshConfig` is called
+ * BEFORE the read and is load-bearing — `set_configuration` writes the config file without refreshing this
+ * process's config object, so a cached read compares against a value that predates the very change the
+ * guard exists to protect and always concludes nothing moved. It narrows the window rather than closing
+ * it; serializing config publication is #2315 step 3.
+ *
+ * `published` must be the entry as read back after publication, not as passed in: only two values that went
+ * through the same write-and-parse round trip are comparable, and comparing against the argument would read
+ * any serialization difference as a concurrent change and skip every undo.
+ */
+function publishedEntryStillStands(published, refreshConfig, readCurrentEntry) {
+	refreshConfig();
+	return isDeepStrictEqual(readCurrentEntry(), published);
+}
+
+/**
+ * Peers that did not answer a stage with `staged: true` — either unreachable, or running a build that
+ * predates staged deploys and therefore treated the request as an ordinary deploy.
+ *
+ * Split out from the caller so it can be tested without a cluster: this is the only safety net for the
+ * mixed-version hazard #2315 records as accepted, and a regression in it fails silently. The entry shape
+ * belongs to harper-pro's replicator rather than this repo — `normalizePeerResult` already tolerates more
+ * than one — so the marker is read flat or from a wrapped body; assuming flat would report every peer in a
+ * fully-upgraded cluster as unconfirmed.
+ */
+function unconfirmedStagingPeers(replicated) {
+	if (!Array.isArray(replicated)) return [];
+	const confirmed = (peer) => peer?.staged === true || peer?.value?.staged === true || peer?.body?.staged === true;
+	return replicated.filter((peer) => peer && !confirmed(peer));
+}
+
 // Ring buffer of install stdout/stderr lines, capped by both line count and bytes so
 // a chatty install can't unbounded-grow the error response. snapshot() reports whether
 // the head was dropped so callers can flag truncation.
@@ -1311,13 +1527,29 @@ async function dropComponent(req) {
 	const componentsRoot = configUtils.getConfigPath(hdbTerms.CONFIG_PARAMS.COMPONENTSROOT);
 	const componentPath = path.join(componentsRoot, project);
 	const pathToComponent = path.join(componentsRoot, projectPath);
+	let restartScope;
 
 	let response;
 	await withComponentPreparationLock(
 		componentPath,
 		async () => {
+			if (req.restart === true) {
+				let runningApplications;
+				try {
+					runningApplications = await manageThreads.getRunningIsolatedApplications(
+						ISOLATED_TOPOLOGY_REQUEST_TIMEOUT_MS
+					);
+				} catch (error) {
+					throw handleHDBError(
+						error,
+						`Cannot drop '${project}' with a restart: the main thread's worker topology is unavailable: ${error.message}`,
+						HTTP_STATUS_CODES.SERVICE_UNAVAILABLE
+					);
+				}
+				if (runningApplications.includes(project)) restartScope = project;
+			}
 			const componentSymlink = path.join(env.get(hdbTerms.CONFIG_PARAMS.ROOTPATH), 'node_modules', project);
-			if (await fs.pathExists(componentSymlink)) {
+			if (!file && (await fs.pathExists(componentSymlink))) {
 				await fs.unlink(componentSymlink);
 			}
 
@@ -1328,7 +1560,7 @@ async function dropComponent(req) {
 			}
 
 			const packageJsonPath = path.join(env.get(hdbTerms.CONFIG_PARAMS.ROOTPATH), 'package.json');
-			if (await fs.pathExists(packageJsonPath)) {
+			if (!file && (await fs.pathExists(packageJsonPath))) {
 				const packageJson = JSON.parse(await fs.readFile(packageJsonPath, 'utf8'));
 				if (packageJson?.dependencies?.[project]) {
 					delete packageJson.dependencies[project];
@@ -1336,11 +1568,8 @@ async function dropComponent(req) {
 				await fs.writeFile(packageJsonPath, JSON.stringify(packageJson, null, 2), 'utf8');
 			}
 
-			configUtils.deleteConfigFromFile([project]);
-			// The main thread's cached config still names the project; the restart below installs every
-			// package application in that cache, and installing this one would take the lock held here.
-			// (A worker's RESTART message refreshes main's config the same way.)
-			if (isMainThread) env.initSync(true);
+			if (!file) configUtils.deleteConfigFromFile([project]);
+			if (!file && isMainThread) env.initSync(true);
 			response = await server.replication.replicateOperation(req);
 			const { applicationHasBranchStorage, removeBranchesForApplication } = require('../resources/branchDatabase.ts');
 			const branched = !file && applicationHasBranchStorage(project);
@@ -1356,6 +1585,7 @@ async function dropComponent(req) {
 				parentPort.postMessage({
 					type: hdbTerms.ITC_EVENT_TYPES.RESTART,
 					workerType: 'http',
+					scope: manageThreads.encodeRestartScope(restartScope),
 					removeBranchesFor: file ? undefined : project,
 				});
 				if (branched) {
@@ -1366,7 +1596,7 @@ async function dropComponent(req) {
 			}
 			const { awaitRestart } = require('./awaitRestart.ts');
 			const restart = await awaitRestart((onProgress) =>
-				manageThreads.restartWorkers('http', undefined, undefined, onProgress)
+				manageThreads.restartWorkers('http', undefined, undefined, onProgress, restartScope)
 			);
 			logRestartOutcome(restart, `dropping ${projectPath}`);
 			if (!branched) return;
@@ -1399,6 +1629,8 @@ exports.addComponent = addComponent;
 exports.dropCustomFunctionProject = dropCustomFunctionProject;
 exports.packageComponent = packageComponent;
 exports.deployComponent = deployComponent;
+exports.unconfirmedStagingPeers = unconfirmedStagingPeers;
+exports.publishedEntryStillStands = publishedEntryStillStands;
 exports.getComponents = getComponents;
 exports.getComponentFile = getComponentFile;
 exports.setComponentFile = setComponentFile;

package/components/operationsValidation.js

@@ -29,6 +29,12 @@ const ENV_KEY_REGEX = /^[\w.-]+$/;
 const HOSTNAME_SCHEMA = Joi.string().hostname();
 const IPV6_SCHEMA = Joi.string().ip({ version: 'ipv6' });
 
+// A deployment id names both an hdb_deployment row and a staging directory, so it is held to the shape
+// the recorder mints — `randomUUID()`, which is lowercase. LOWERCASE ONLY, because a case-insensitive
+// filesystem resolves an uppercase id to the real directory while every string compare against it fails:
+// the retention pin would not recognise the artifact the request is about to activate, and would evict it.
+const DEPLOYMENT_ID_REGEX = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
+
 module.exports = {
 	getDropCustomFunctionValidator,
 	setCustomFunctionValidator,
@@ -492,7 +498,32 @@ function deployComponentValidator(req) {
 			.required()
 			.messages({ 'string.pattern.base': HDB_ERROR_MSGS.BAD_PROJECT_NAME }),
 		package: Joi.string().optional(),
-		restart: Joi.alternatives().try(Joi.boolean(), Joi.string().valid('rolling')).optional(),
+		// `activate: false` builds and certifies the component, then stops, leaving an artifact a later
+		// request activates by `deployment_id`. STRICT: `validateBySchema` throws away Joi's converted
+		// value, so a coercing boolean would let `activate: "false"` validate here and then read as truthy
+		// in the handler — deploying the very release the caller asked not to make live.
+		activate: Joi.boolean().strict().optional(),
+		// Activate a build staged earlier by `activate: false`. It becomes a path segment
+		// (`.deploy-staging/<id>/<component>`), so the charset is pinned as tightly as the value it names.
+		deployment_id: Joi.string().pattern(DEPLOYMENT_ID_REGEX).optional().messages({
+			'string.pattern.base': `'deployment_id' must be a UUID`,
+		}),
+		// Set by deployComponent from the origin's deployment row and carried to peers by replication.
+		// Validated because it is a path segment on EVERY deploy and unknown keys are admitted, so an
+		// operator-supplied one would otherwise reach the filesystem unchecked.
+		_deploymentId: Joi.string().pattern(DEPLOYMENT_ID_REGEX).optional().messages({
+			'string.pattern.base': `'_deploymentId' must be a UUID`,
+		}),
+		restart: Joi.alternatives()
+			.try(Joi.boolean(), Joi.string().valid('rolling'))
+			.optional()
+			// Nothing goes live, so there is nothing to restart into.
+			.when('activate', {
+				is: false,
+				then: Joi.forbidden().messages({
+					'any.unknown': `'restart' cannot be combined with 'activate: false': staging does not change the running component`,
+				}),
+			}),
 		install_command: Joi.string().optional(),
 		install_timeout: Joi.number().optional(),
 		install_allow_scripts: Joi.boolean().optional(),
@@ -534,6 +565,7 @@ function deployComponentValidator(req) {
 		// like urlPath/host above, not component config: reusing assertBranchedDatabases here (rather
 		// than re-deriving its rules in Joi) gives a synchronous 400 at deploy time instead of a load
 		// failure discovered much later and disconnected from the request that caused it.
+		isolated: Joi.boolean().optional(),
 		branchedDatabases: Joi.custom((value, helpers) => {
 			try {
 				assertBranchedDatabases(req.project, value);
@@ -575,7 +607,22 @@ function deployComponentValidator(req) {
 		}),
 	})
 		.with('urlPath', 'package')
-		.with('host', 'package');
+		.with('host', 'package')
+		// An activation has no build inputs and takes no routing or packaging opinions: the artifact's own
+		// descriptor is the authority for what it publishes, and silently ignoring these would hide that.
+		.without('deployment_id', [
+			'package',
+			'payload',
+			'activate',
+			'install_command',
+			'install_timeout',
+			'install_allow_scripts',
+			'credentials',
+			'urlPath',
+			'host',
+			'branchedDatabases',
+			'isolated',
+		]);
 
 	return validator.validateBySchema(req, deployProjSchema);
 }

package/components/packageComponent.ts

@@ -1,4 +1,4 @@
-import { join, relative, sep } from 'node:path';
+import { basename, join, relative, sep } from 'node:path';
 import { stat, readdir } from 'node:fs/promises';
 import { Readable, pipeline } from 'node:stream';
 import tar from 'tar-fs';
@@ -13,6 +13,27 @@ const DEFAULT_OPTIONS: PackageOptions = { skip_node_modules: false, skip_symlink
 
 const WEBPACK_CACHE_SEGMENT = join('cache', 'webpack');
 
+/**
+ * `node_modules/harper` is Harper's, whatever is on disk there.
+ *
+ * Every non-root component load runs `symlinkHarperModule`, which does `rmSync(harperModule, {
+ * recursive: true, force: true })` and then links the running install (`components/componentLoader.ts`).
+ * It does that whether or not the path already existed, so component content there survives no load and
+ * packaging it cannot be preserving component source — while packaging it walks the whole install, since
+ * the packer dereferences symlinks and recurses into linked directories.
+ *
+ * `harperdb` is deliberately NOT here, and the asymmetry is the reason: the loader only *repairs*
+ * `node_modules/harperdb` when that path already exists. A legacy component shipping a real
+ * npm-installed `harperdb` that has never been loaded on this host therefore owns it — and excluding it
+ * would strip it from the tarball, after which `installApplication` skips installing (it returns early
+ * when `node_modules` exists), the loader's present-gate never fires, and `import from 'harperdb'`
+ * fails on the target — and that holds whether the path is skipped by name or by resolved identity,
+ * because an archive that simply OMITS it cannot restore it. So a `harperdb` link to the install is
+ * still followed. Closing that means packing a placeholder at the path so the loader's present-gate can
+ * fire on the target, not skipping it; tracked in harper#2577.
+ */
+const INSTALL_OWNED_PATH = join('node_modules', 'harper');
+
 /**
  * Whether `fullPath` (an absolute path under `directory`) should be excluded from the package when
  * `skip_node_modules` is set. The path is first made relative to `directory`, so packaging a component
@@ -21,6 +42,9 @@ const WEBPACK_CACHE_SEGMENT = join('cache', 'webpack');
  * excluded the whole tree. Shared by the stream packer and the directory walk so they cannot diverge.
  */
 function isExcluded(directory: string, fullPath: string, options: PackageOptions): boolean {
+	// Unconditional, including under `skip_symlinks`: packed literally, the link ships an absolute path to
+	// the packaging host's install root, which arrives dangling.
+	if (basename(fullPath) === 'harper' && relative(directory, fullPath) === INSTALL_OWNED_PATH) return true;
 	if (!options.skip_node_modules) return false;
 	const rel = relative(directory, fullPath);
 	return rel.split(sep).includes('node_modules') || rel.includes(WEBPACK_CACHE_SEGMENT);

package/components/requestRestart.ts

@@ -24,6 +24,17 @@ export function requestRestart() {
 	restartArrayBuffer.notify();
 }
 
+export function requestRestartAfterDeploy(
+	isNewComponent: boolean,
+	packageMetadataChanged: boolean,
+	wasIsolated: boolean,
+	isIsolated: boolean
+): boolean {
+	if (!isNewComponent && !packageMetadataChanged && wasIsolated === isIsolated) return false;
+	requestRestart();
+	return true;
+}
+
 export function restartNeeded() {
 	ensureInitialized();
 	return restartNeededArray[0] === 1;