@harperfast/harper 5.3.0 → 5.3.1

package/bin/copyDb.ts

@@ -15,7 +15,7 @@ import OpenEnvironmentObject from '../utility/lmdb/OpenEnvironmentObject.ts';
 import { OpenDBIObject } from '../utility/lmdb/OpenDBIObject.ts';
 import { INTERNAL_DBIS_NAME, AUDIT_STORE_NAME } from '../utility/lmdb/terms.ts';
 import { CONFIG_PARAMS, DATABASES_DIR_NAME, MIGRATING_DIR_SUFFIX } from '../utility/hdbTerms.ts';
-import { AUDIT_STORE_OPTIONS, auditRetention } from '../resources/auditStore.ts';
+import { AUDIT_STORE_OPTIONS, auditRetention, stampDatabaseGeneration } from '../resources/auditStore.ts';
 import { blobsReadmeContent, copyBlobRootsByIndex } from '../dataLayer/blobBackup.ts';
 import { describeSchema } from '../dataLayer/schemaDescribe.ts';
 import { updateConfigValue } from '../config/configUtils.ts';
@@ -983,6 +983,10 @@ export async function copyDbToRocks(sourceRootStore, sourceDatabase: string, tar
 			targetRootStore.putSync(REMOTE_NODE_IDS_KEY, asBinary(idMappingBytes));
 		}
 
+		// flushed so the stamp is durable before the caller publishes the staging directory
+		stampDatabaseGeneration(targetRootStore, { carriesLog: false });
+		await targetRootStore.flush({ allowWriteStall: true });
+
 		console.log('migrated database ' + sourceDatabase + ' to RocksDB');
 	} finally {
 		endPendingMigrationBlobSaves();

package/bin/deployRenderer.ts

@@ -149,6 +149,9 @@ export class DeployRenderer {
 				this.output.write(`error: ${e.message ?? message.data}${e.code ? ` (${e.code})` : ''}\n`);
 				break;
 			}
+			case 'warning':
+				this.output.write(`warning: ${(parsed as { message?: string })?.message ?? message.data}\n`);
+				break;
 			case 'done':
 				// Caller picks up final result via the SSE iterator; nothing to render here.
 				break;

package/components/Application.ts

@@ -37,6 +37,14 @@ import {
 	formatDeploymentProvenance,
 	parseDeploymentProvenance,
 } from './deploymentProvenance.ts';
+import {
+	fingerprintInstall,
+	gitSourceIdentity,
+	packedSourceIdentity,
+	PACKAGE_LOCK_FILES,
+	UNIDENTIFIED_SOURCE,
+	type InstallFingerprint,
+} from './installFingerprint.ts';
 
 import { basename, dirname, extname, isAbsolute, join, relative, sep, win32 } from 'node:path';
 import {
@@ -490,8 +498,9 @@ async function resolveCommittish(application: Application, committish: string, c
 async function packGitReferenceWithoutScripts(
 	application: Application,
 	gitRef: GitReference,
-	parentDirPath: string
-): Promise<string> {
+	parentDirPath: string,
+	identifySource: boolean
+): Promise<{ path: string; commit?: string }> {
 	const cloneDir = await mkdtemp(join(tmpdir(), 'harper-git-clone-'));
 	try {
 		const { code: cloneCode, stderr: cloneStderr } = await nonInteractiveSpawn(
@@ -537,22 +546,37 @@ async function packGitReferenceWithoutScripts(
 			await writeFile(manifestPath, JSON.stringify(manifest, null, 2));
 		}
 
-		return await runNpmPack(application, ['pack', '--json', '--ignore-scripts', cloneDir], parentDirPath);
+		const commit = identifySource ? await checkedOutCommit(application, cloneDir) : undefined;
+		const packed = await runNpmPack(application, ['pack', '--json', '--ignore-scripts', cloneDir], parentDirPath);
+		return { path: packed.path, commit };
 	} finally {
 		await rm(cloneDir, { recursive: true, force: true });
 	}
 }
 
+/** Naming the source is only a report, so git failing to answer never fails the deploy. */
+async function checkedOutCommit(application: Application, cloneDir: string): Promise<string | undefined> {
+	try {
+		const { code, stdout } = await nonInteractiveSpawn(application.name, 'git', ['rev-parse', 'HEAD'], cloneDir);
+		return code === 0 ? stdout : undefined;
+	} catch {
+		return undefined;
+	}
+}
+
+type PackedTarball = { path: string; name?: string; version?: string; integrity?: string };
+
 /**
- * Runs `npm pack` with the given args and returns the resulting tarball's path under `cwd`. Shared
- * between the git-reference reclone path above and the plain identifier path in extractApplication.
+ * Runs `npm pack` with the given args and returns the resulting tarball's path under `cwd`, with the name, version
+ * and integrity npm reported for it. Shared between the git-reference reclone path above and the plain identifier
+ * path in extractApplication.
  */
 async function runNpmPack(
 	application: Application,
 	packArgs: string[],
 	cwd: string,
 	gitCredentialEnv?: Record<string, string>
-): Promise<string> {
+): Promise<PackedTarball> {
 	const { stdout, code, stderr } = await nonInteractiveSpawn(
 		application.name,
 		'npm',
@@ -573,7 +597,7 @@ async function runNpmPack(
 		throw new Error(`Failed to download package ${application.packageIdentifier}: ${stderr}`);
 	}
 
-	let packResult: Array<{ filename: string }>;
+	let packResult: Array<{ filename: string; name?: unknown; version?: unknown; integrity?: unknown }>;
 	try {
 		packResult = JSON.parse(stdout.slice(stdout.indexOf('[')));
 	} catch (err) {
@@ -585,7 +609,14 @@ async function runNpmPack(
 		throw new Error(`Unexpected npm pack output for ${application.packageIdentifier}:\n${stdout}`);
 	}
 
-	return join(cwd, packResult[0].filename);
+	const [packed] = packResult;
+	const text = (value: unknown) => (typeof value === 'string' ? value : undefined);
+	return {
+		path: join(cwd, packed.filename),
+		name: text(packed.name),
+		version: text(packed.version),
+		integrity: text(packed.integrity),
+	};
 }
 
 // Hidden directory under the components root holding component versions renamed aside
@@ -656,15 +687,6 @@ type ExtractionContext = Pick<Application, 'name' | 'dirPath' | 'logger'>;
 // module (both in source and in dist), holds no secret, and is inert without a live session.
 export const GIT_CREDENTIAL_HELPER_PATH = join(__dirname, 'gitCredentialHelper.js');
 
-const PACKAGE_LOCK_FILES = [
-	'package-lock.json',
-	'npm-shrinkwrap.json',
-	'pnpm-lock.yaml',
-	'yarn.lock',
-	'bun.lock',
-	'bun.lockb',
-];
-
 type InstalledPackageMetadata = {
 	files: Map<string, Buffer>;
 	readable: boolean;
@@ -783,7 +805,10 @@ type ResolvedTarball =
 	| { kind: 'link'; sourceDirPath: string };
 
 /** Resolve `payload` or `package` into a tarball stream. Touches neither the live tree nor staging. */
-async function resolveApplicationTarball(application: Application): Promise<ResolvedTarball> {
+async function resolveApplicationTarball(
+	application: Application,
+	{ identifySource = false }: { identifySource?: boolean } = {}
+): Promise<ResolvedTarball> {
 	let tarballPath: string | undefined;
 	let tarball: Readable;
 	let shouldDeleteTarball = false;
@@ -809,6 +834,8 @@ async function resolveApplicationTarball(application: Application): Promise<Reso
 		// If the package identifier is a file path we need to check if its a tarball or a directory
 		if (application.packageIdentifier.startsWith('file:')) {
 			const packagePath = application.packageIdentifier.slice(5);
+			// Each node reads its own copy of a local path, so nothing here names what it holds.
+			if (identifySource) application.sourceIdentity = UNIDENTIFIED_SOURCE;
 			try {
 				// Have to remove the 'file:' prefix in order to use fs methods
 				const stats = await stat(packagePath);
@@ -880,7 +907,9 @@ async function resolveApplicationTarball(application: Application): Promise<Reso
 			}
 
 			if (gitRef) {
-				tarballPath = await packGitReferenceWithoutScripts(application, gitRef, parentDirPath);
+				const packed = await packGitReferenceWithoutScripts(application, gitRef, parentDirPath, identifySource);
+				tarballPath = packed.path;
+				if (identifySource) application.sourceIdentity = gitSourceIdentity(packed.commit);
 			} else {
 				const packArgs = ['pack', '--json', packageIdentifierForPack];
 				if (!allowScripts) {
@@ -892,7 +921,15 @@ async function resolveApplicationTarball(application: Application): Promise<Reso
 							`can read the git credential. Unset install_allow_scripts to keep the credential out of their reach.`
 					);
 				}
-				tarballPath = await runNpmPack(application, packArgs, parentDirPath, application.gitCredentialEnv);
+				const packed = await runNpmPack(application, packArgs, parentDirPath, application.gitCredentialEnv);
+				tarballPath = packed.path;
+				if (identifySource) {
+					const fromRegistry =
+						packageIdentifierForPack === application.packageIdentifier &&
+						!looksLikeGitReference(packageIdentifierForPack) &&
+						!/^https?:\/\//i.test(packageIdentifierForPack);
+					application.sourceIdentity = packedSourceIdentity(fromRegistry, packed);
+				}
 			}
 			shouldDeleteTarball = true;
 			tarball = createReadStream(tarballPath);
@@ -3534,7 +3571,7 @@ async function discardCandidate(application: Application, deploymentId: string):
 export async function buildCandidateApplication(
 	application: Application,
 	deploymentId: string,
-	options: { rejectLinkSource?: boolean } = {}
+	options: { rejectLinkSource?: boolean; fingerprint?: boolean } = {}
 ): Promise<string> {
 	const deploymentDirPath = candidateDeploymentDirPath(application.dirPath, deploymentId);
 	const candidateDirPath = candidateApplicationPath(application.dirPath, deploymentId);
@@ -3543,7 +3580,7 @@ export async function buildCandidateApplication(
 	try {
 		// Replaced, not extracted into: a prior attempt on this id may have left a partial tree.
 		await rm(candidateDirPath, { recursive: true, force: true });
-		const resolved = await resolveApplicationTarball(application);
+		const resolved = await resolveApplicationTarball(application, { identifySource: options.fingerprint });
 		if (resolved.kind === 'link' && options.rejectLinkSource) {
 			// What the operator asked for, not a server fault: the same component deploys immediately.
 			throw new ClientError(
@@ -3578,6 +3615,9 @@ export async function buildCandidateApplication(
 		if (resolved.kind !== 'link') {
 			await writeDeploymentProvenance(candidateDirPath, application.name, deploymentId);
 		}
+		if (options.fingerprint) {
+			application.installFingerprint = await fingerprintInstall(candidateDirPath, application.sourceIdentity);
+		}
 		return candidateDirPath;
 	} catch (error) {
 		await discardCandidate(application, deploymentId);
@@ -4534,6 +4574,8 @@ export class Application {
 	packageMetadataChanged: boolean = false;
 	installationIsOpaque: boolean = false;
 	alreadyActive: boolean = false;
+	sourceIdentity?: string;
+	installFingerprint?: InstallFingerprint;
 
 	constructor({ name, payload, packageIdentifier, install, onInstallLine, credentials }: ApplicationOptions) {
 		this.name = name;
@@ -4721,6 +4763,7 @@ export type PrepareApplicationOptions = {
 	describeArtifact?: () => { rootConfig: Record<string, unknown> | null; isolated: boolean };
 	/** `activate` only: admit the artifact's isolation intent under the preparation lock, before the swap. */
 	admitIsolation?: (descriptor: ArtifactDescriptor) => Promise<void>;
+	fingerprintInstall?: boolean;
 };
 
 export async function prepareApplication(application: Application, options: PrepareApplicationOptions = {}) {
@@ -4789,6 +4832,7 @@ export async function prepareApplication(application: Application, options: Prep
 						await application.startGitCredentialSession();
 						candidateDirPath = await buildCandidateApplication(application, artifactId, {
 							rejectLinkSource: mode === 'stage',
+							fingerprint: options.fingerprintInstall,
 						});
 					} finally {
 						await application.cleanupGitCredentialSession();

package/components/DESIGN.md

@@ -41,7 +41,8 @@ The ordering is the design. Three things used to be wrong, the first two in a wa
 
 - **The live tree was moved aside first**, so the component was broken for the whole extract +
   `npm install`. Worse than unavailable — the live path held the _new_ code before its dependencies were
-  installed, so requests during a deploy hit an unrunnable tree. `stage-swap-availability.test.ts`
+  installed, so requests during a deploy hit an unrunnable tree.
+  `integrationTests/deploy/stage-swap-availability.test.ts`
   samples the live path through a deliberately blocked install and fails against the old ordering.
 - **Validation ran after the swap committed**, so a component that installed cleanly but threw at load
   went live anyway while the operation returned an error. Validation is now a callback preparation
@@ -248,8 +249,7 @@ boundary settles config to the same end state as the tree. `deploy_component` on
 (`describeArtifact`); `prepareApplication` turns the declaration into a `RootConfigEffect`
 (`components/rootConfigPublication.ts`) and `activateCandidateApplication` owns applying it:
 
-- `set` — a package build publishes the entry it was declared with, replacing the component's entry whole,
-  as `addConfig` did.
+- `set` — a package build publishes the entry it was declared with, replacing the component's entry whole.
 - `unset-package` — a payload build removes `package`, `install` and `credentials` and keeps the rest
   (`isolated`, `urlPath`, `host`, `branchedDatabases`), removing the entry if nothing remains. "No package"
   is an opinion: left in place, a cold install resolves the old package over the payload release that is
@@ -303,9 +303,9 @@ could never settle. The reverse direction is not covered: a build before this ch
 fails that component closed, so settle every interrupted activation (a clean start does) before downgrading.
 
 **One writer, one lock, durable.** `applyRootConfigEffect` is the only runtime read-modify-write of the root
-config document besides `set_configuration`, which takes the same lock around `updateConfigValue` — and that
-reads and writes the same file the lock is keyed by, the one boot reads. `addConfig` and `deleteConfigFromFile`
-are gone — the latter wrote to a path rebuilt from the document's `rootPath` rather than the file it parsed. The
+config document besides `set_configuration` and the deprecated `drop_custom_function_project`'s removal from
+the legacy `apps` list, both of which take the same lock around `updateConfigValue` — and that reads and writes
+the same file the lock is keyed by, the one boot reads, not a path rebuilt from the document's `rootPath`. The
 lock is the component preparation lock primitive keyed by `getRootConfigFilePath()`, which names the file boot
 reads whenever a boot source exists and so is fixed for the life of the process — not a configured path
 `set_configuration` could move under a concurrent writer. Lock order is always
@@ -372,7 +372,8 @@ removed — doing that for retained builds on every pass made a healthy componen
 sibling threads at boot and be deferred with nothing in progress. A lock a live deploy holds is still recorded as
 that same deferral: "do not delete" is not "safe to load". The deploy path prunes inside the settlement scan
 it already runs under the lock, before building, so a deploy pays one traversal of the staging root.
-`dropComponentDirectory` reclaims the dropped component's dormant builds, since no later deploy of that
+`drop_component` reclaims the dropped component's dormant builds (`retireComponentDirectory(...).discard()`),
+since no later deploy of that
 name will. Only ENOENT is absence; any other read error keeps the entry and moves on. Pruning is disk
 hygiene: it never fails a component closed and never replaces a deploy's own error, so the bound is
 best-effort under filesystem failure and is not a storage quota — journaled, unsettled and unowned
@@ -454,13 +455,13 @@ it. An older build reads a record as residue and removes it, and a kept release
 can activate; the marker is an ignored file to it. The journal format is unchanged. A peer on an older build
 answers 404 to a consumed id, as before. `deployment_stagingRetention_maxCount` (default 5) now bounds kept
 releases with staged builds, and each is a whole installed tree, so at the default a component holds up to five
-extra copies of itself; `0` keeps no previous release, and the rest of this section still applies. Until #2315
-step 7, a package component reinstalls from its source on the first start after each package deploy; that
-reinstall keeps no record, but the certified tree it displaces is kept, which is the one worth keeping.
+extra copies of itself; `0` keeps no previous release, and the rest of this section still applies. A package
+component reinstalls from its source on the first start after each package deploy (#2315 step 7 shipped as
+reporting only, #2929); that reinstall keeps no record, but the certified tree it displaces is kept, which is the one worth keeping.
 
 ## Component preparation is serialized across worker threads
 
-`prepareApplication()` performs one transaction per component: build the replacement, validate it, then swap it in (see "A deploy builds off to the side" below). Deploy operations can execute on worker threads as well as main, so a module-local promise queue is insufficient—each worker has its own module registry. `withComponentPreparationLock()` (`components/componentPreparationLock.ts`) instead acquires an atomic filesystem lock keyed by the absolute component path. The deprecated `install_node_modules` operation uses the same lock, so it cannot run npm concurrently with a deploy.
+`prepareApplication()` performs one transaction per component: build the replacement, validate it, then swap it in (see "A deploy builds off to the side" above). Deploy operations can execute on worker threads as well as main, so a module-local promise queue is insufficient—each worker has its own module registry. `withComponentPreparationLock()` (`components/componentPreparationLock.ts`) instead acquires an atomic filesystem lock keyed by the absolute component path. The deprecated `install_node_modules` operation uses the same lock, so it cannot run npm concurrently with a deploy.
 
 The deploy lifecycle broadcast deliberately sits _outside_ the lock. Overlapping requests therefore increment the existing per-component lifecycle refcount before queueing; watchers remain suppressed continuously until the final queued preparation ends. The lock itself covers credential materialization, extraction, and installation. Its fully-written owner record is published with an atomic rename, so contenders never observe a partially initialized lock. A preparation caller never steals a lock from a known-live owner based on elapsed wall time: installs can be long-running and clocks can jump. Locks from a dead process are reclaimed, and a same-process contender asks the main thread whether the owning worker still exists so a worker crash does not wedge that component until Harper restarts. A ticket its owner could not remove — a Windows sharing violation, a scanner holding the file — would name a finished holder that is still alive, so a release whose unlink keeps failing publishes a `<lockName>.released.<token>` marker instead, which contenders honour by clearing both. Only the ticket's owner writes one, after confirming it still owns the ticket — or, when a scanner holding the ticket without read sharing hides its record, knowing it can only be its own, since the ticket's name carries its token — and tokens are never reused, so a marker cannot retire a holder that has not finished. A process running an older build ignores markers, so overlapping processes of mixed versions do not get this guarantee, and a ticket left live-looking before the upgrade stays until that process restarts. Windows refuses to open a claim whose unlink is in progress (`EPERM`) until the unlinking handle closes, so a contender retries that read until the claim reads or is gone; one that stays unreadable fails the scan instead of reading as absent, since dropping a live ticket would admit a second holder. An older build fails the acquire on that `EPERM`. The boot-time bulk-recovery probe is deliberately different: it never renews its 250 ms deadline, even behind another live recovery, so it can defer that component and let the worker bind its listener.
 
@@ -482,29 +483,11 @@ candidate tree is complete before validation starts and nothing else writes to i
 wait for. `unitTests/components/componentLoader.test.js` ("deploy validation loads never wait on a
 deploy") holds both routes and the plain timeout.
 
-### The component load lock is keyed by plugin type, so a plugin's promise is everyone's clock
-
-`sequentiallyHandleApplication` (`components/componentLoader.ts`) holds a cross-thread lock keyed by the
-plugin TYPE name — `graphqlSchema`, `rest`, … — not by the component. That is deliberate. Plugin modules
-are per-thread singletons carrying module-level state (`server/http.ts`'s `universalHeaders` ownership
-array, `resources/graphql.ts`'s `knownGraphQLDirectives`, the scheduler's register-inside-the-lock
-contract), and applications load _concurrently_: `serializeComponentLoad` serializes per application
-name and all applications go into one `Promise.all`. Without this key two applications' `handleApplication`
-for the same plugin would interleave on a single thread, not merely across threads.
-
-The price of that key is that whatever a plugin does inside the lock is paid by every other application.
-So a plugin must return a promise that settles with its real outcome: the `withDeployAwareTimeout`
-watchdog exists for a _hang_, never as the reporting path for a failure the plugin already diagnosed. A
-success-only wait is what turned one unparseable schema into 30s of instance-wide gating per broken
-component (#1917). `Scope.waitForInitialLoads()` is that promise — it resolves once the entry handler's
-initial scan and every operation that scan started have completed, and rejects with the first failure,
-after draining the rest so no sibling operation outlives the lock. The watchdog can still cut that drain
-short, so the serialization the lock buys is bounded by the timeout rather than absolute.
-
-Extraction renames an existing component aside before writing the replacement and keeps it until
-dependency installation and metadata verification complete. Any preparation failure atomically
-renames the partial tree into hidden staging before restoring the prior tree, so a live writer cannot
-wedge rollback with `ENOTEMPTY`; cleanup completes while the same-component lock is still held.
+Since #2345 no preparation extracts in place; the live tree moves aside only at activation. What
+remains is the legacy recovery pass (`recoverOrCleanupStaleExtractionPaths`), whose
+`rollbackExtractedDirectory` atomically renames whatever holds the live path into hidden staging before
+restoring the prior tree, so a live writer cannot wedge rollback with `ENOTEMPTY`; cleanup completes
+while the same-component lock is still held.
 On non-root POSIX systems, rollback uses a mode-`000` placeholder to keep that writer out between
 retries. Before moving or removing it, rollback verifies the placeholder's device/inode identity and
 restores owner permissions because a cross-parent directory move updates `..` and requires write
@@ -521,8 +504,9 @@ and configuration mutations under that lock, so cleanup residue cannot resurrect
 component and a concurrent deploy cannot interleave with the drop. Peer replication begins after
 the local lock is released, and each peer serializes its own drop independently. Full-component drops
 rename the live tree into staging before best-effort cleanup, avoiding an in-place recursive-delete
-race with the running worker. Recovery is durable across a process crash. It relies on rename/create
-ordering rather than `fsync`, so a host power loss can lose the marker.
+race with the running worker. Recovery is durable across a process crash. The legacy pass relies on
+rename/create ordering rather than `fsync`, so a host power loss can lose its marker; activation and drop
+flush theirs.
 
 A package-manager timeout must not release this lock while npm descendants are still mutating `node_modules`. POSIX spawns therefore run in a dedicated process group; timeout sends the group `SIGTERM`, escalates to `SIGKILL`, and waits for exit before rejecting. Windows uses `taskkill /T /F` for the equivalent process-tree termination. `manageThreads` tracks each spawned process tree by its owning Harper thread and force-terminates it if that worker exits, preventing detached installers from surviving a worker restart or Harper shutdown. `SIGKILL`/`taskkill` only queue termination, so a worker's dead-owner reclamation (above) waits for that thread's tracked process groups to be confirmed gone, not merely signaled—otherwise a replacement preparation could start while the old writer might still be alive. A process group a dead worker's own event loop spawned is never reaped from another thread, so it persists as a zombie rather than fully disappearing; since a zombie can no longer touch the filesystem, confirmation treats a zombie the same as a fully reaped exit.
 
@@ -553,6 +537,36 @@ type detection remains asynchronous in extraction. Bare absolute Windows directo
 npm's copy/pack behavior rather than becoming live links; explicit `file:` and relative directory
 inputs retain their existing symlink behavior.
 
+### The component load lock is keyed by application and plugin
+
+`sequentiallyHandleApplication` (`components/componentLoader.ts`) holds a cross-thread lock keyed by the
+application and the plugin type, `${appName}\0${pluginName}` (#2884, for #3184): one application's load of one
+plugin is serialized across threads. Keyed by the plugin type alone, one application's hung
+`handleApplication` timed out every other application's load of that plugin; NUL separates the two
+because `appName` can contain dots and slashes.
+
+Before #2884 the plugin-wide key was also deliberate for a reason #2884 did not revisit: plugin
+modules are per-thread singletons carrying module-level state (`server/http.ts`'s `universalHeaders`
+ownership array, `resources/graphql.ts`'s `knownGraphQLDirectives`, the scheduler's
+register-inside-the-lock contract), and applications load _concurrently_ — `serializeComponentLoad`
+serializes per application name and all applications go into one `Promise.all` — so two
+applications' `handleApplication` for the same plugin can now interleave on a single thread. Each of
+those three tolerates it: the http plugin's `handleApplication` is synchronous and only its first
+(root) invocation owns the security headers, `knownGraphQLDirectives` is filled at module load and
+only read in `handleApplication`, and the scheduler keys registration by application name behind an
+idempotent `startSchedulerEngine()`. A plugin that keeps per-thread state across an `await` inside
+`handleApplication` would not.
+
+The price of the lock is that whatever a plugin does inside it is paid by that application's load of
+the plugin on every other thread.
+So a plugin must return a promise that settles with its real outcome: the `withDeployAwareTimeout`
+watchdog exists for a _hang_, never as the reporting path for a failure the plugin already diagnosed. A
+success-only wait is what turned one unparseable schema into 30s of instance-wide gating per broken
+component (#1917). `Scope.waitForInitialLoads()` is that promise — it resolves once the entry handler's
+initial scan and every operation that scan started have completed, and rejects with the first failure,
+after draining the rest so no sibling operation outlives the lock. The watchdog can still cut that drain
+short, so the serialization the lock buys is bounded by the timeout rather than absolute.
+
 ## Peer-side deploy_component payload read: retryable blob stalls and `Readable.from()` cancellation
 
 `readPayloadBlobWithRetry` (`components/deploymentRecorder.ts`) wraps the peer's read of a replicated `hdb_deployment` row's `payload_blob` so a transient 503 `BlobReadError` (`BLOB_UNAVAILABLE_STATUS`, `resources/blob.ts`) — content bytes not arriving within `blobReadTimeout`, e.g. a parked blob send on the origin — retries instead of failing the whole deploy. Two non-obvious constraints shaped the design:
@@ -585,6 +599,45 @@ the outcome there is unknown.
 It stays a `failed` peer result, because `getFailedPeers()` counts only that status, and a new one would
 read as success.
 
+## A replicated deploy reports each node's install fingerprint, and never acts on it
+
+Every node of a replicated `deploy_component` resolves and installs the release itself, so two nodes can end
+up with different code and nothing says so (#2295). Moving the release between nodes was ruled out: shipping
+the built tree (#2917, closed) was too heavy, and a strict tree check would refuse a mixed-platform cluster.
+So each node records what it installed, and the origin reports a difference without acting on it.
+
+- **The fingerprint** (`components/installFingerprint.ts`) is taken only for a deploy or a stage, after the
+  install and before the swap (`fingerprintInstall`, a `prepareApplication` option). It has two parts:
+  - `source` is the resolver's own name for what it packed, never a second hash. It is `git:<commit>` from
+    Harper's clone, `npm:<name>@<version>` from `npm pack --json` for a registry spec (a tag resolves to one),
+    or npm's reported `integrity:<sri>` for a git spec npm packed itself, or a tarball URL. A source the
+    resolver could not name is `unidentified`, which never matches. So is a local `file:` path, because each
+    node reads its own copy. The one exception is an absolute directory path given without `file:` on Windows:
+    Harper copies it through `npm pack` instead of linking it, so npm's reported integrity for that copy names
+    it. A payload has no `source`: its peers read the origin's blob. Only a fingerprinting build asks git for the
+    commit, and a git failure there leaves the source `unidentified` rather than failing the deploy.
+  - `lockfiles` is the sha256 of each root lockfile in `PACKAGE_LOCK_FILES`, by name. An absent lockfile is
+    not listed. One that can't be read is `{ unreadable: <code> }`, never absent.
+- **The comparison** runs once, on the origin, on the aggregate `response.replicated`, just before the
+  recorder re-records it (`markInstallComparisons`, `components/operations.js`). So the per-peer callback's
+  entries are replaced rather than contradicted.
+  - Each peer gets `install_matches` and `install_differs`. `install_matches` is `false` when anything
+    compared differs. Otherwise it is `null` when any evidence is missing, unreadable or `unidentified`, as
+    from an older Harper or a failed peer, and `true` only when everything compared matches.
+  - Only lockfile names this node recognizes are compared.
+- **Where it shows:**
+  - one `warning` event, which the CLI prints;
+  - a sentence on the final message, added after staging replaces the message;
+  - the per-peer fields in `peer_results`, which `normalizePeerResult` keeps only once a comparison ran;
+  - the origin's own fingerprint, in the row's `install_fingerprint`.
+- **It never changes the outcome.** Drift alone keeps success. A real peer failure still fails the deploy,
+  after the warning has fired.
+
+A match means equal evidence, not identical trees. A custom `install_command` can install different
+dependencies and leave the same lockfile, or none. Lockfiles written against different registry mirrors
+differ while the code matches. This prevents nothing, and a restart can still re-resolve a package component
+(`installConfiguredApplication`) with no report.
+
 ## A dangling symlink silently truncates the deploy tarball (`components/packageComponent.ts`)
 
 Packaging uses `tar-fs.pack(dir, { dereference: true })` by default (`skip_symlinks` off).

package/components/componentLoader.ts

@@ -50,6 +50,7 @@ import * as mqtt from '../server/mqtt.ts';
 import { getConfigFilePath, getConfigObj, getConfigPath } from '../config/configUtils.ts';
 import { bootstrapModels, startModelsConfigHotReload } from '../resources/models/bootstrap.ts';
 import { declareDecisionTablesAtBoot } from '../resources/models/decisionStore.ts';
+import { declareCalibrationsTableAtBoot } from '../resources/models/calibrationStore.ts';
 import { ErrorResource } from '../resources/ErrorResource.ts';
 import { Scope } from './Scope.ts';
 import { ApplicationScope } from './ApplicationScope.ts';
@@ -895,6 +896,7 @@ export async function loadComponent(
 			await bootstrapModels(config);
 			startModelsConfigHotReload();
 			declareDecisionTablesAtBoot();
+			declareCalibrationsTableAtBoot();
 		}
 
 		// The `env:` block declares the component's environment expectations (string literal →

package/components/deploymentRecorder.ts

@@ -17,6 +17,7 @@ import { transaction, contextStorage } from '../resources/transaction.ts';
 import { createBlob, isSaving, deleteBlob, BLOB_UNAVAILABLE_STATUS } from '../resources/blob.ts';
 import * as terms from '../utility/hdbTerms.ts';
 import type { CredentialReference } from './secretOperations.ts';
+import { isInstallFingerprint } from './installFingerprint.ts';
 import { ClientError } from '../utility/errors/hdbError.ts';
 import { logger } from '../utility/logging/logger.ts';
 import { hostname } from 'node:os';
@@ -93,11 +94,13 @@ interface CreateOptions {
  */
 function withIsolatedTransaction<T>(write: () => Promise<T>, timeoutMs?: number): Promise<T> {
 	const ambient = contextStorage.getStore();
+	// No `signal`: tracking is observability and the deploy must still succeed, so a deploy client that
+	// stops waiting (CLI ^C, proxy idle timeout) must not poison these writes and strand the row in a
+	// non-terminal phase.
 	const context = {
 		user: ambient?.user,
 		originatingOperation: ambient?.originatingOperation,
 		session: ambient?.session,
-		signal: ambient?.signal,
 	};
 	return transaction(context, (txn) => {
 		if (timeoutMs != null) {
@@ -742,6 +745,20 @@ function normalizePeerResult(raw: unknown): Record<string, unknown> {
 			: null,
 		started_at: r.started_at ?? null,
 		completed_at: r.completed_at ?? null,
+		...installComparisonFields(r),
+	};
+}
+
+/** Present only once the origin compared this peer's install fingerprint with its own. */
+function installComparisonFields(r: Record<string, unknown>): Record<string, unknown> {
+	if (!('install_matches' in r)) return {};
+	const install = r.install ?? (r.value as any)?.install ?? (r.body as any)?.install;
+	return {
+		install: isInstallFingerprint(install) ? install : null,
+		install_matches: typeof r.install_matches === 'boolean' ? r.install_matches : null,
+		install_differs: Array.isArray(r.install_differs)
+			? r.install_differs.filter((name) => typeof name === 'string')
+			: [],
 	};
 }
 

package/components/installFingerprint.ts

@@ -0,0 +1,123 @@
+import { createHash } from 'node:crypto';
+import { createReadStream } from 'node:fs';
+import { join } from 'node:path';
+
+export const PACKAGE_LOCK_FILES = [
+	'package-lock.json',
+	'npm-shrinkwrap.json',
+	'pnpm-lock.yaml',
+	'yarn.lock',
+	'bun.lock',
+	'bun.lockb',
+];
+
+export type UnreadableLockfile = { unreadable: string };
+
+/** A packed source the resolver could not name: evidence of nothing, so it never matches. */
+export const UNIDENTIFIED_SOURCE = 'unidentified';
+
+/**
+ * What an install came from, as the resolver already identified it — `npm:<name>@<version>`, `git:<commit>`, or
+ * npm's `integrity:<sri>` for a source that has neither — and each root lockfile it left, by file name: its sha256,
+ * or why it could not be read. An absent lockfile is not listed; a payload has no `source`.
+ */
+export type InstallFingerprint = { source?: string; lockfiles: Record<string, string | UnreadableLockfile> };
+
+/** `matches` is false when anything differs, else null when any evidence is missing, unreadable or unidentified. */
+export type InstallComparison = { matches: boolean | null; differs: string[]; peerSource?: string };
+
+export async function fingerprintInstall(treePath: string, source?: string): Promise<InstallFingerprint> {
+	const digests = await Promise.all(PACKAGE_LOCK_FILES.map((name) => hashLockfile(join(treePath, name))));
+	const lockfiles: InstallFingerprint['lockfiles'] = {};
+	PACKAGE_LOCK_FILES.forEach((name, index) => {
+		if (digests[index] !== undefined) lockfiles[name] = digests[index];
+	});
+	return source === undefined ? { lockfiles } : { source, lockfiles };
+}
+
+async function hashLockfile(filePath: string): Promise<string | UnreadableLockfile | undefined> {
+	const hash = createHash('sha256');
+	try {
+		for await (const chunk of createReadStream(filePath)) hash.update(chunk);
+	} catch (error) {
+		const code = (error as NodeJS.ErrnoException | undefined)?.code;
+		return code === 'ENOENT' ? undefined : { unreadable: typeof code === 'string' ? code : 'EUNKNOWN' };
+	}
+	return hash.digest('hex');
+}
+
+const COMMIT = /^(?:[0-9a-f]{40}|[0-9a-f]{64})$/;
+
+export function gitSourceIdentity(commit: string | undefined): string {
+	const trimmed = commit?.trim();
+	return trimmed && COMMIT.test(trimmed) ? `git:${trimmed}` : UNIDENTIFIED_SOURCE;
+}
+
+/**
+ * A registry spec, a tag included, resolves to a `name@version` that can never change. A git spec npm packed itself,
+ * or a tarball URL, has no such name, so npm's own integrity for what it packed stands in.
+ */
+export function packedSourceIdentity(
+	fromRegistry: boolean,
+	packed: { name?: string; version?: string; integrity?: string }
+): string {
+	if (fromRegistry) return packed.name && packed.version ? `npm:${packed.name}@${packed.version}` : UNIDENTIFIED_SOURCE;
+	return packed.integrity ? `integrity:${packed.integrity}` : UNIDENTIFIED_SOURCE;
+}
+
+const SHA256_HEX = /^[0-9a-f]{64}$/;
+const SOURCE = /^(?:(?:npm|git|integrity):\S{1,512}|unidentified)$/;
+const identified = (source: string | undefined) => source !== undefined && source !== UNIDENTIFIED_SOURCE;
+
+export function isInstallFingerprint(value: unknown): value is InstallFingerprint {
+	const fingerprint = value as InstallFingerprint | undefined;
+	const lockfiles = fingerprint?.lockfiles;
+	if (!lockfiles || typeof lockfiles !== 'object' || Array.isArray(lockfiles)) return false;
+	if (
+		fingerprint.source !== undefined &&
+		!(typeof fingerprint.source === 'string' && SOURCE.test(fingerprint.source))
+	) {
+		return false;
+	}
+	return Object.values(lockfiles).every((digest) =>
+		typeof digest === 'string' ? SHA256_HEX.test(digest) : typeof digest?.unreadable === 'string'
+	);
+}
+
+/** Only the lockfile names this node recognizes are compared, so a peer that recognizes more is not a difference. */
+export function compareInstallFingerprints(own: InstallFingerprint | undefined, peer: unknown): InstallComparison {
+	if (!isInstallFingerprint(own) || !isInstallFingerprint(peer)) return { matches: null, differs: [] };
+	const differs: string[] = [];
+	let unavailable = false;
+	if (own.source !== undefined || peer.source !== undefined) {
+		if (!identified(own.source) || !identified(peer.source)) unavailable = true;
+		else if (own.source !== peer.source) differs.push('source');
+	}
+	for (const name of PACKAGE_LOCK_FILES) {
+		const mine = own.lockfiles[name];
+		const theirs = peer.lockfiles[name];
+		if (mine === undefined && theirs === undefined) continue;
+		if (mine === undefined || theirs === undefined) differs.push(name);
+		else if (typeof mine !== 'string' || typeof theirs !== 'string') unavailable = true;
+		else if (mine !== theirs) differs.push(name);
+	}
+	const comparison: InstallComparison = { matches: differs.length > 0 ? false : unavailable ? null : true, differs };
+	if (differs.includes('source')) comparison.peerSource = peer.source;
+	return comparison;
+}
+
+export function describeInstallDrift(
+	peers: Array<{ node: string | null; comparison: InstallComparison }>
+): string | undefined {
+	const differing = peers.filter((peer) => peer.comparison.matches === false);
+	if (differing.length === 0) return undefined;
+	const detail = differing
+		.map(({ node, comparison }) => {
+			const fields = comparison.differs.map((field) =>
+				field === 'source' && comparison.peerSource ? `source ${comparison.peerSource}` : field
+			);
+			return `${node ?? 'unknown'} (${fields.join(', ')})`;
+		})
+		.join(', ');
+	return `Install fingerprints differ from this node's on ${differing.length} of ${peers.length} peer node(s): ${detail}.`;
+}

package/components/mcp/DESIGN.md

@@ -51,12 +51,12 @@ A handful of design points are non-obvious and easy to break:
   honor its `post`/`patch` overrides, matching REST — previously they bound to the base table class and
   silently bypassed those overrides. Advertised CRUD output schemas are still table-derived, so an overridden
   write verb whose return diverges from `{ id }`/`{ ok }`/`{ deleted }` advertises a subset shape (the in-use
-  SDK tolerates supersets; tightening per-override envelopes is sibling-issue work — see the `derive.ts`
+  SDK tolerates supersets; tightening per-override envelopes is sibling-issue work — see the `tools/schemas/derive.ts`
   envelope note).
 
 - **Resource subscriptions are row-backed via the audit log.** `resources/subscribe` resolves the URI to a
-  Resource and drives `Table.subscribe` off the audit-store `'committed'` path (same machinery as the
-  "Audit-store `'committed'` notification batching" section above). The targeting is the subtle part:
+  Resource and drives `Table.subscribe` off the audit-store `'committed'` path (same machinery as
+  [Audit-store `'committed'` notification batching](../../resources/DESIGN.md#audit-store-committed-notification-batching-transactionbroadcastts)). The targeting is the subtle part:
   `getMatch` returns the matched Resource plus the remaining path on `relativeURL`, and `subscribeToResource`
   sets **both** `request.id` (the record key, or `undefined`) **and** `request.isCollection` from it. A record
   URI (`…/WorkItem/42`) watches that record; a collection URI (`…/WorkItem`, what `resources/list` advertises)
@@ -81,7 +81,7 @@ A handful of design points are non-obvious and easy to break:
 - **Test seams avoid loading thread/audit machinery in unit tests.** `_setSubscribeImplForTest`
   (`resources.ts`) and `_setItcForTest` (`serverRequests.ts`) inject fakes so the unit suite needn't spin up
   the audit log or ITC. Consequence: the subscribe **targeting** logic (`id`/`isCollection` derivation) is
-  _bypassed_ by the seam and is therefore covered at the **integration** level (`sse-listchanged.test.ts` N3
+  _bypassed_ by the seam and is therefore covered at the **integration** level (`integrationTests/mcp/sse-listchanged.test.ts` N3
   record / N4 collection), not in unit tests.
 
 - **Discovery filtering must mirror dispatch's ORDER _and_ its name namespace.**