@nextclaw/app-runtime 0.9.15 → 0.11.0

package/dist/services/app-installation.service.js

@@ -1,19 +1,31 @@
 import { AppManifestService } from "./app-manifest.service.js";
-import { isAppComponentManifestBundle, isAppStandaloneManifestBundle } from "../types/app-manifest.types.js";
+import { isAppComponentManifestBundle } from "../types/app-manifest.types.js";
 import { AppBundleService } from "./app-bundle.service.js";
 import { AppHomeService } from "./app-home.service.js";
+import { FileLockService } from "./file-lock.service.js";
+import { AppInstanceStorageService } from "./app-instance-storage.service.js";
+import { AppInstallationIntegrityService } from "./app-installation-integrity.service.js";
+import { AppInstallationFilesystemService } from "./app-installation-filesystem.service.js";
+import { AppInstallationLifecycleService } from "./app-installation-lifecycle.service.js";
 import { AppBuildService } from "./app-build.service.js";
 import { AppRegistryConfigService } from "./app-registry-config.service.js";
 import { AppRemoteRegistryClientService } from "./app-remote-registry-client.service.js";
 import { AppRegistryService } from "./app-registry.service.js";
 import { AppInstallSourceService } from "./app-install-source.service.js";
-import { randomUUID } from "node:crypto";
-import { access, cp, mkdir, readdir, rename, rm } from "node:fs/promises";
+import { rm } from "node:fs/promises";
 import path from "node:path";
+import { AsyncLocalStorage } from "node:async_hooks";
 //#region src/services/app-installation.service.ts
+const SAFE_APP_ID_PATTERN = /^[a-z0-9]+(?:[.-][a-z0-9]+)*$/;
 var AppInstallationService = class {
 	installSourceService;
-	constructor(appHomeService = new AppHomeService(), bundleService = new AppBundleService(), manifestService = new AppManifestService(), buildService = new AppBuildService(), registryService = new AppRegistryService(appHomeService), registryConfigService = new AppRegistryConfigService(appHomeService), remoteRegistryClient = new AppRemoteRegistryClientService(new AppRegistryConfigService(appHomeService))) {
+	instanceStorageService;
+	fileLockService = new FileLockService();
+	integrityService;
+	filesystemService;
+	lifecycleService;
+	appOperationContext = new AsyncLocalStorage();
+	constructor(appHomeService = new AppHomeService(), bundleService = new AppBundleService(), manifestService = new AppManifestService(), buildService = new AppBuildService(), registryService = new AppRegistryService(appHomeService), registryConfigService = new AppRegistryConfigService(appHomeService), remoteRegistryClient = new AppRemoteRegistryClientService(new AppRegistryConfigService(appHomeService)), instanceStorageService) {
 		this.appHomeService = appHomeService;
 		this.bundleService = bundleService;
 		this.manifestService = manifestService;
@@ -21,98 +33,49 @@ var AppInstallationService = class {
 		this.registryService = registryService;
 		this.registryConfigService = registryConfigService;
 		this.remoteRegistryClient = remoteRegistryClient;
-		this.installSourceService = new AppInstallSourceService(this.manifestService, this.remoteRegistryClient);
+		this.installSourceService = new AppInstallSourceService(this.manifestService, this.remoteRegistryClient, this.bundleService);
+		this.instanceStorageService = instanceStorageService ?? new AppInstanceStorageService(appHomeService);
+		this.integrityService = new AppInstallationIntegrityService(manifestService);
+		this.filesystemService = new AppInstallationFilesystemService({
+			buildService,
+			integrityService: this.integrityService,
+			manifestService
+		});
+		this.lifecycleService = new AppInstallationLifecycleService({
+			registryService,
+			registryConfigService,
+			remoteRegistryClient,
+			instanceStorageService: this.instanceStorageService,
+			integrityService: this.integrityService,
+			install: this.install,
+			rollback: this.rollback
+		});
 	}
-	install = async (appSource, options) => {
-		const { onProgress, registryUrl } = options ?? {};
+	install = async (appSource, options = {}) => {
+		const { onProgress, registryUrl } = options;
 		await onProgress?.("resolving");
 		const source = await this.installSourceService.resolve(appSource, registryUrl);
 		const tempDirectory = await this.appHomeService.createTemporaryDirectory("napp-install-");
 		try {
-			if (source.kind === "registry") await onProgress?.("downloading");
-			const bundlePath = source.kind === "directory" ? (await this.bundleService.packAppDirectory({
-				appDirectory: source.appDirectory,
-				outputPath: path.join(tempDirectory, "app.napp")
-			})).bundlePath : source.kind === "bundle" ? source.bundlePath : (await this.remoteRegistryClient.downloadBundle({
-				resolution: source.registryResolution,
-				targetDirectory: tempDirectory
-			})).bundlePath;
+			const bundlePath = await this.installSourceService.materializeBundle(source, tempDirectory, onProgress);
 			await onProgress?.("verifying");
 			const extractedDirectory = path.join(tempDirectory, "bundle");
 			const extractedMetadata = await this.bundleService.extractBundle({
 				bundlePath,
 				targetDirectory: extractedDirectory
 			});
-			await this.materializeDistribution({
+			await this.filesystemService.materializeDistribution({
 				appDirectory: extractedDirectory,
 				distributionMode: extractedMetadata.metadata.distributionMode
 			});
 			const manifestBundle = await this.manifestService.load(extractedDirectory);
-			const installDirectory = this.appHomeService.getInstallDirectory(manifestBundle.manifest.id, manifestBundle.manifest.version);
-			if (source.kind === "registry" && manifestBundle.manifest.id !== source.registryResolution.appId) throw new Error(`bundle manifest.appId 与 registry 请求不一致：期望 ${source.registryResolution.appId}，实际 ${manifestBundle.manifest.id}`);
-			await onProgress?.("installing");
-			const dataDirectory = this.appHomeService.getAppDataDirectory(manifestBundle.manifest.id);
-			await this.copyToImmutableInstallDirectory({
-				appId: manifestBundle.manifest.id,
-				appVersion: manifestBundle.manifest.version,
+			return await this.installPreparedBundle({
+				source,
 				extractedDirectory,
-				installDirectory
+				extractedMetadata,
+				manifestBundle,
+				options
 			});
-			await mkdir(dataDirectory, { recursive: true });
-			await onProgress?.("finalizing");
-			let registryRecord;
-			try {
-				registryRecord = await this.registryService.upsertInstallation({
-					appId: manifestBundle.manifest.id,
-					name: manifestBundle.manifest.name,
-					description: manifestBundle.manifest.description,
-					version: manifestBundle.manifest.version,
-					installDirectory,
-					dataDirectory,
-					sourceKind: source.kind,
-					distributionMode: source.kind === "registry" ? source.registryResolution.distributionMode : extractedMetadata.metadata.distributionMode,
-					sourceRef: source.sourceRef,
-					installedAt: (/* @__PURE__ */ new Date()).toISOString(),
-					permissions: manifestBundle.manifest.schemaVersion === 1 ? manifestBundle.manifest.permissions ?? {} : {},
-					registryUrl: source.kind === "registry" ? source.registryResolution.registryUrl : void 0,
-					bundleUrl: source.kind === "registry" ? source.registryResolution.bundleUrl : void 0,
-					sha256: source.kind === "registry" ? source.registryResolution.sha256 : void 0,
-					publisher: source.kind === "registry" ? source.registryResolution.publisher : void 0,
-					manifestSchemaVersion: manifestBundle.manifest.schemaVersion,
-					components: isAppComponentManifestBundle(manifestBundle) ? manifestBundle.components.map((component) => ({
-						...component,
-						componentDirectory: path.join(installDirectory, component.path),
-						manifestPath: path.join(installDirectory, component.path, component.kind === "panel" ? "panel-app.json" : "service-app.json")
-					})) : void 0,
-					primaryPanelId: isAppComponentManifestBundle(manifestBundle) ? manifestBundle.primaryPanelId : void 0
-				});
-			} catch (error) {
-				await rm(installDirectory, {
-					recursive: true,
-					force: true
-				});
-				throw error;
-			}
-			const activeVersionRecord = registryRecord.installedVersions[registryRecord.activeVersion];
-			return {
-				appId: registryRecord.appId,
-				name: registryRecord.name,
-				version: registryRecord.activeVersion,
-				installDirectory,
-				dataDirectory,
-				sourceKind: source.kind,
-				sourceRef: source.sourceRef,
-				distributionMode: registryRecord.installedVersions[registryRecord.activeVersion]?.distributionMode,
-				permissions: registryRecord.installedVersions[registryRecord.activeVersion]?.permissions ?? {},
-				registryUrl: registryRecord.installedVersions[registryRecord.activeVersion]?.registryUrl,
-				bundleUrl: registryRecord.installedVersions[registryRecord.activeVersion]?.bundleUrl,
-				sha256: registryRecord.installedVersions[registryRecord.activeVersion]?.sha256,
-				publisher: registryRecord.installedVersions[registryRecord.activeVersion]?.publisher,
-				enabled: registryRecord.enabled,
-				manifestSchemaVersion: activeVersionRecord?.manifestSchemaVersion ?? 1,
-				components: activeVersionRecord?.components,
-				primaryPanelId: activeVersionRecord?.primaryPanelId
-			};
 		} finally {
 			await rm(tempDirectory, {
 				recursive: true,
@@ -120,117 +83,104 @@ var AppInstallationService = class {
 			});
 		}
 	};
-	update = async (appId, options) => {
-		const { onProgress, registryUrl: requestedRegistryUrl, version } = options ?? {};
-		await onProgress?.("resolving");
-		const appRecord = await this.registryService.getApp(appId);
-		if (!appRecord) throw new Error(`未找到已安装应用：${appId}`);
-		const activeVersionRecord = appRecord.installedVersions[appRecord.activeVersion];
-		const registryUrl = requestedRegistryUrl ?? activeVersionRecord?.registryUrl ?? (await this.registryConfigService.getSnapshot()).currentUrl;
-		const resolution = await this.remoteRegistryClient.resolve({
+	installPreparedBundle = async (prepared) => {
+		const appId = prepared.manifestBundle.manifest.id;
+		return await this.withAppOperation(appId, async () => await this.commitPreparedInstall(prepared));
+	};
+	commitPreparedInstall = async (prepared) => {
+		const { extractedDirectory, extractedMetadata, manifestBundle, options, source } = prepared;
+		const { onProgress } = options;
+		const { id: appId, version } = manifestBundle.manifest;
+		const installDirectory = this.appHomeService.getInstallDirectory(appId, version);
+		if (source.kind === "registry" && appId !== source.registryResolution.appId) throw new Error(`bundle manifest.appId 与 registry 请求不一致：期望 ${source.registryResolution.appId}，实际 ${appId}`);
+		await onProgress?.("installing");
+		const existingRecord = await this.registryService.getApp(appId);
+		const publisher = source.kind === "registry" ? source.registryResolution.publisher : options.trustedPublisher;
+		const currentPublisher = existingRecord?.publisher ?? existingRecord?.installedVersions[existingRecord.activeVersion]?.publisher;
+		if (currentPublisher && currentPublisher.id !== publisher?.id) throw new Error(`应用 ${appId} 已绑定发布者 ${currentPublisher.id}，拒绝由 ${publisher?.id ?? "未验证本地来源"} 覆盖。`);
+		const dataSchemaVersion = manifestBundle.manifest.schemaVersion === 2 ? manifestBundle.manifest.storage?.schemaVersion ?? 1 : 1;
+		if (existingRecord?.defaultInstance.dataSchemaVersion !== void 0 && existingRecord.defaultInstance.dataSchemaVersion !== dataSchemaVersion) throw new Error(`应用 ${appId} 数据 schema 从 ${existingRecord.defaultInstance.dataSchemaVersion} 升级到 ${dataSchemaVersion}，但包内没有受支持的迁移合同。更新已停止，现有数据和版本保持不变。`);
+		const instanceDirectory = this.appHomeService.getAppInstanceDirectory(appId, "default");
+		const instanceExisted = await this.integrityService.pathExists(instanceDirectory);
+		const contentSha256 = await this.filesystemService.copyToImmutableInstallDirectory({
 			appId,
-			version,
-			registryUrl
+			appVersion: version,
+			extractedDirectory,
+			installDirectory
 		});
-		if (resolution.version === appRecord.activeVersion) {
-			if (!activeVersionRecord) throw new Error(`已安装应用缺少激活版本：${appId}`);
-			return {
-				appId: appRecord.appId,
-				name: appRecord.name,
-				version: appRecord.activeVersion,
-				previousVersion: appRecord.activeVersion,
-				installDirectory: activeVersionRecord.installDirectory,
-				dataDirectory: appRecord.dataDirectory,
-				sourceKind: activeVersionRecord.sourceKind,
-				sourceRef: activeVersionRecord.sourceRef,
-				permissions: activeVersionRecord.permissions,
-				registryUrl: activeVersionRecord.registryUrl,
-				bundleUrl: activeVersionRecord.bundleUrl,
-				sha256: activeVersionRecord.sha256,
-				publisher: activeVersionRecord.publisher,
-				enabled: appRecord.enabled,
-				manifestSchemaVersion: activeVersionRecord.manifestSchemaVersion,
-				components: activeVersionRecord.components,
-				primaryPanelId: activeVersionRecord.primaryPanelId,
-				updated: false
-			};
-		}
-		const installedTarget = appRecord.installedVersions[resolution.version];
-		if (installedTarget) {
-			await onProgress?.("verifying");
-			await onProgress?.("installing");
-			await this.rollback(appId, resolution.version);
-			await onProgress?.("finalizing");
-			return {
-				appId: appRecord.appId,
-				name: appRecord.name,
-				version: resolution.version,
-				previousVersion: appRecord.activeVersion,
-				installDirectory: installedTarget.installDirectory,
-				dataDirectory: appRecord.dataDirectory,
-				sourceKind: installedTarget.sourceKind,
-				distributionMode: installedTarget.distributionMode,
-				sourceRef: installedTarget.sourceRef,
-				permissions: installedTarget.permissions,
-				registryUrl: installedTarget.registryUrl,
-				bundleUrl: installedTarget.bundleUrl,
-				sha256: installedTarget.sha256,
-				publisher: installedTarget.publisher,
-				enabled: appRecord.enabled,
-				manifestSchemaVersion: installedTarget.manifestSchemaVersion,
-				components: installedTarget.components,
-				primaryPanelId: installedTarget.primaryPanelId,
-				updated: true
-			};
-		}
-		return {
-			...await this.install(`${appId}@${resolution.version}`, {
-				registryUrl,
-				onProgress
-			}),
-			previousVersion: appRecord.activeVersion,
-			updated: true
-		};
-	};
-	uninstall = async (appId, purgeData) => {
-		const appRecord = await this.registryService.getApp(appId);
-		if (!appRecord) throw new Error(`未找到已安装应用：${appId}`);
-		const removedVersions = Object.keys(appRecord.installedVersions).sort((left, right) => left.localeCompare(right));
-		const stagedPaths = [];
-		const stagePath = async (originalPath) => {
-			if (!await this.pathExists(originalPath)) return;
-			const stagedPath = `${originalPath}.uninstalling-${randomUUID()}`;
-			await rename(originalPath, stagedPath);
-			stagedPaths.push({
-				originalPath,
-				stagedPath
-			});
-		};
-		const restoreStagedPaths = async () => {
-			for (const entry of [...stagedPaths].reverse()) if (await this.pathExists(entry.stagedPath)) await rename(entry.stagedPath, entry.originalPath);
-		};
+		const defaultInstance = await this.instanceStorageService.materializeDefaultInstance({
+			appId,
+			publisherId: (currentPublisher ?? publisher)?.id,
+			legacyDataDirectory: existingRecord?.defaultInstance.storage.layout === "legacy" ? existingRecord.dataDirectory : void 0,
+			dataSchemaVersion
+		});
+		await onProgress?.("finalizing");
+		let registryRecord;
 		try {
-			for (const versionRecord of Object.values(appRecord.installedVersions)) await stagePath(versionRecord.installDirectory);
-			if (purgeData) await stagePath(appRecord.dataDirectory);
-			if (!await this.registryService.removeApp(appId)) throw new Error(`卸载过程中应用记录已发生变化：${appId}`);
+			registryRecord = await this.registryService.upsertInstallation({
+				appId,
+				name: manifestBundle.manifest.name,
+				description: manifestBundle.manifest.description,
+				version,
+				installDirectory,
+				defaultInstance,
+				sourceKind: source.kind,
+				distributionMode: source.kind === "registry" ? source.registryResolution.distributionMode : extractedMetadata.metadata.distributionMode,
+				sourceRef: source.sourceRef,
+				installedAt: (/* @__PURE__ */ new Date()).toISOString(),
+				permissions: manifestBundle.manifest.schemaVersion === 1 ? manifestBundle.manifest.permissions ?? {} : this.manifestService.resolvePlatformSecurity(manifestBundle.manifest).permissions,
+				registryUrl: source.kind === "registry" ? source.registryResolution.registryUrl : void 0,
+				bundleUrl: source.kind === "registry" ? source.registryResolution.bundleUrl : void 0,
+				sha256: source.kind === "registry" ? source.registryResolution.sha256 : void 0,
+				publisher,
+				manifestSchemaVersion: manifestBundle.manifest.schemaVersion,
+				components: isAppComponentManifestBundle(manifestBundle) ? manifestBundle.components.map((component) => ({
+					...component,
+					componentDirectory: path.join(installDirectory, component.path),
+					manifestPath: path.join(installDirectory, component.path, component.kind === "panel" ? "panel-app.json" : "service-app.json")
+				})) : void 0,
+				primaryPanelId: isAppComponentManifestBundle(manifestBundle) ? manifestBundle.primaryPanelId : void 0,
+				security: isAppComponentManifestBundle(manifestBundle) ? this.manifestService.resolvePlatformSecurity(manifestBundle.manifest) : void 0,
+				dataSchemaVersion,
+				contentSha256,
+				activate: options.activate
+			});
 		} catch (error) {
-			try {
-				await restoreStagedPaths();
-			} catch (restoreError) {
-				throw new AggregateError([error, restoreError], `卸载 ${appId} 失败，且无法完全恢复已暂存文件。`);
-			}
+			await this.integrityService.removeDirectory(installDirectory);
+			if (!instanceExisted) await this.instanceStorageService.rollbackNewInstance({
+				instance: defaultInstance,
+				legacyDataDirectory: existingRecord?.defaultInstance.storage.layout === "legacy" ? existingRecord.dataDirectory : void 0
+			});
 			throw error;
 		}
-		await Promise.all(stagedPaths.map((entry) => rm(entry.stagedPath, {
-			recursive: true,
-			force: true
-		})));
+		const installedVersion = registryRecord.installedVersions[version];
 		return {
-			appId,
-			removedVersions,
-			dataRemoved: purgeData
+			appId: registryRecord.appId,
+			name: registryRecord.name,
+			version,
+			installDirectory,
+			dataDirectory: defaultInstance.storage.dataDirectory,
+			instance: registryRecord.defaultInstance,
+			sourceKind: source.kind,
+			sourceRef: source.sourceRef,
+			distributionMode: installedVersion?.distributionMode,
+			permissions: installedVersion?.permissions ?? {},
+			registryUrl: installedVersion?.registryUrl,
+			bundleUrl: installedVersion?.bundleUrl,
+			sha256: installedVersion?.sha256,
+			publisher: installedVersion?.publisher,
+			enabled: registryRecord.enabled,
+			manifestSchemaVersion: installedVersion?.manifestSchemaVersion ?? 1,
+			components: installedVersion?.components,
+			primaryPanelId: installedVersion?.primaryPanelId
 		};
 	};
+	update = async (appId, options) => {
+		return await this.withAppOperation(appId, async () => await this.lifecycleService.update(appId, options));
+	};
+	uninstall = async (appId, purgeData) => {
+		return await this.withAppOperation(appId, async () => await this.lifecycleService.uninstall(appId, purgeData));
+	};
 	list = async () => {
 		return (await this.registryService.listApps()).map((appRecord) => ({
 			appId: appRecord.appId,
@@ -245,12 +195,74 @@ var AppInstallationService = class {
 	};
 	reconcileFilesystem = async () => {
 		await this.appHomeService.ensureBaseDirectories();
-		const appRecords = await this.registryService.listApps();
+		let appRecords = await this.registryService.listApps();
+		for (const appRecord of appRecords) await this.withAppOperation(appRecord.appId, async () => {
+			for (const versionRecord of Object.values(appRecord.installedVersions)) {
+				if (!await this.integrityService.pathExists(versionRecord.installDirectory)) continue;
+				if (!versionRecord.contentSha256) {
+					const contentSha256 = await this.integrityService.calculateDigest(versionRecord.installDirectory);
+					await this.registryService.setVersionContentDigest(appRecord.appId, versionRecord.version, contentSha256);
+				}
+				await this.integrityService.protectDirectory(versionRecord.installDirectory);
+			}
+		});
+		appRecords = await this.registryService.listApps();
 		const referencedInstallPaths = new Set(appRecords.flatMap((record) => Object.values(record.installedVersions).map((version) => path.resolve(version.installDirectory))));
-		const referencedDataPaths = new Set(appRecords.map((record) => path.resolve(record.dataDirectory)));
-		const packageDirectories = await this.readDirectories(this.appHomeService.getPackagesDirectory());
-		for (const appDirectory of packageDirectories) await this.reconcileGeneratedSiblings(appDirectory, referencedInstallPaths);
-		await this.reconcileGeneratedSiblings(this.appHomeService.getDataDirectory(), referencedDataPaths);
+		const referencedDataPaths = new Set(appRecords.map((record) => path.resolve(record.defaultInstance.storage.layout === "instance-v1" ? record.defaultInstance.storage.instanceDirectory : record.dataDirectory)));
+		const packageDirectories = await this.filesystemService.readDirectories(this.appHomeService.getPackagesDirectory());
+		for (const appDirectory of packageDirectories) await this.filesystemService.reconcileGeneratedSiblings(appDirectory, referencedInstallPaths);
+		await this.filesystemService.reconcileGeneratedSiblings(this.appHomeService.getDataDirectory(), referencedDataPaths);
+		for (const appRecord of appRecords) {
+			if (appRecord.defaultInstance.storage.layout !== "instance-v1") continue;
+			await this.filesystemService.reconcileGeneratedSiblings(appRecord.defaultInstance.storage.instanceDirectory, new Set([path.resolve(appRecord.defaultInstance.storage.dataDirectory)]));
+		}
+		for (const appRecord of appRecords) {
+			if (appRecord.defaultInstance.storage.layout !== "legacy") continue;
+			await this.withAppOperation(appRecord.appId, async () => {
+				const currentRecord = await this.registryService.getApp(appRecord.appId);
+				if (!currentRecord || currentRecord.defaultInstance.storage.layout !== "legacy") return;
+				const activeVersion = currentRecord.installedVersions[currentRecord.activeVersion];
+				if (!activeVersion) throw new Error(`已安装应用缺少激活版本：${currentRecord.appId}`);
+				const instance = await this.instanceStorageService.materializeDefaultInstance({
+					appId: currentRecord.appId,
+					publisherId: currentRecord.publisher?.id,
+					legacyDataDirectory: currentRecord.dataDirectory,
+					dataSchemaVersion: currentRecord.defaultInstance.dataSchemaVersion
+				});
+				try {
+					await this.registryService.upsertInstallation({
+						appId: currentRecord.appId,
+						name: currentRecord.name,
+						description: currentRecord.description,
+						version: currentRecord.activeVersion,
+						installDirectory: activeVersion.installDirectory,
+						defaultInstance: instance,
+						sourceKind: activeVersion.sourceKind,
+						sourceRef: activeVersion.sourceRef,
+						installedAt: activeVersion.installedAt,
+						distributionMode: activeVersion.distributionMode,
+						permissions: activeVersion.permissions,
+						registryUrl: activeVersion.registryUrl,
+						bundleUrl: activeVersion.bundleUrl,
+						sha256: activeVersion.sha256,
+						publisher: currentRecord.publisher ?? activeVersion.publisher,
+						manifestSchemaVersion: activeVersion.manifestSchemaVersion,
+						components: activeVersion.components,
+						primaryPanelId: activeVersion.primaryPanelId,
+						security: activeVersion.security,
+						dataSchemaVersion: activeVersion.dataSchemaVersion,
+						contentSha256: activeVersion.contentSha256,
+						enabled: currentRecord.enabled
+					});
+				} catch (error) {
+					await this.instanceStorageService.rollbackNewInstance({
+						instance,
+						legacyDataDirectory: currentRecord.dataDirectory
+					});
+					throw error;
+				}
+			});
+		}
 	};
 	info = async (appId) => {
 		const appRecord = await this.registryService.getApp(appId);
@@ -263,6 +275,9 @@ var AppInstallationService = class {
 			activeVersion: appRecord.activeVersion,
 			enabled: appRecord.enabled,
 			dataDirectory: appRecord.dataDirectory,
+			instance: appRecord.defaultInstance,
+			storage: appRecord.defaultInstance.storage,
+			storageUsage: await this.instanceStorageService.measureUsage(appRecord.defaultInstance.storage),
 			installedVersions: installedVersions.map((versionRecord) => ({
 				version: versionRecord.version,
 				installDirectory: versionRecord.installDirectory,
@@ -277,41 +292,73 @@ var AppInstallationService = class {
 				publisher: versionRecord.publisher,
 				manifestSchemaVersion: versionRecord.manifestSchemaVersion,
 				components: versionRecord.components,
-				primaryPanelId: versionRecord.primaryPanelId
+				primaryPanelId: versionRecord.primaryPanelId,
+				contentSha256: versionRecord.contentSha256
 			})),
 			grants: appRecord.grants
 		};
 	};
 	setEnabled = async (appId, enabled) => {
-		const appRecord = await this.registryService.setEnabled(appId, enabled);
-		return {
-			appId: appRecord.appId,
-			activeVersion: appRecord.activeVersion,
-			enabled: appRecord.enabled
-		};
+		return await this.withAppOperation(appId, async () => {
+			const appRecord = await this.registryService.setEnabled(appId, enabled);
+			return {
+				appId: appRecord.appId,
+				activeVersion: appRecord.activeVersion,
+				enabled: appRecord.enabled
+			};
+		});
 	};
 	rollback = async (appId, version) => {
-		const currentRecord = await this.registryService.getApp(appId);
-		if (!currentRecord) throw new Error(`未找到已安装应用：${appId}`);
-		if (currentRecord.activeVersion === version) return {
-			appId,
-			activeVersion: version,
-			previousVersion: version,
-			enabled: currentRecord.enabled,
-			rolledBack: false
-		};
-		const targetVersion = currentRecord.installedVersions[version];
-		if (!targetVersion) throw new Error(`应用 ${appId} 未安装版本 ${version}。`);
-		const targetManifest = await this.manifestService.load(targetVersion.installDirectory);
-		if (targetManifest.manifest.id !== appId || targetManifest.manifest.version !== version) throw new Error(`回滚目标 ${appId}@${version} 校验失败。`);
-		const appRecord = await this.registryService.activateVersion(appId, version);
-		return {
+		return await this.withAppOperation(appId, async () => {
+			const currentRecord = await this.registryService.getApp(appId);
+			if (!currentRecord) throw new Error(`未找到已安装应用：${appId}`);
+			if (currentRecord.activeVersion === version) return {
+				appId,
+				activeVersion: version,
+				previousVersion: version,
+				enabled: currentRecord.enabled,
+				rolledBack: false
+			};
+			const targetVersion = currentRecord.installedVersions[version];
+			if (!targetVersion) throw new Error(`应用 ${appId} 未安装版本 ${version}。`);
+			if (targetVersion.dataSchemaVersion !== currentRecord.defaultInstance.dataSchemaVersion) throw new Error(`应用 ${appId}@${version} 需要数据 schema ${targetVersion.dataSchemaVersion}，当前实例为 ${currentRecord.defaultInstance.dataSchemaVersion}。没有可用 checkpoint，已阻止回滚。`);
+			await this.assertVersionIntegrity(appId, version);
+			const appRecord = await this.registryService.activateVersion(appId, version);
+			return {
+				appId,
+				activeVersion: appRecord.activeVersion,
+				previousVersion: currentRecord.activeVersion,
+				enabled: appRecord.enabled,
+				rolledBack: true
+			};
+		});
+	};
+	assertVersionIntegrity = async (appId, version) => {
+		const appRecord = await this.registryService.getApp(appId);
+		if (!appRecord) throw new Error(`未找到已安装应用：${appId}`);
+		const targetVersion = version ?? appRecord.activeVersion;
+		const versionRecord = appRecord.installedVersions[targetVersion];
+		if (!versionRecord) throw new Error(`应用 ${appId} 未安装版本 ${targetVersion}。`);
+		const contentSha256 = await this.integrityService.assertVersion({
 			appId,
-			activeVersion: appRecord.activeVersion,
-			previousVersion: currentRecord.activeVersion,
-			enabled: appRecord.enabled,
-			rolledBack: true
-		};
+			version: targetVersion,
+			versionRecord
+		});
+		if (!versionRecord.contentSha256) {
+			await this.registryService.setVersionContentDigest(appId, targetVersion, contentSha256);
+			await this.integrityService.protectDirectory(versionRecord.installDirectory);
+		}
+	};
+	withAppOperation = async (appId, operation) => {
+		if (!SAFE_APP_ID_PATTERN.test(appId)) throw new Error(`appId 不是安全的 App 操作标识：${appId}`);
+		const lockPath = path.resolve(this.appHomeService.getAppOperationLockPath(appId));
+		const activeLocks = this.appOperationContext.getStore();
+		if (activeLocks?.has(lockPath)) return await operation();
+		return await this.fileLockService.withLock(lockPath, async () => {
+			const nextLocks = new Set(activeLocks ?? []);
+			nextLocks.add(lockPath);
+			return await this.appOperationContext.run(nextLocks, operation);
+		});
 	};
 	resolveLaunch = async (appReference, explicitDocumentGrantMap) => {
 		const sourceType = await this.installSourceService.detectLocal(appReference, false);
@@ -323,10 +370,12 @@ var AppInstallationService = class {
 		if (!appRecord) throw new Error(`未找到应用目录，也未找到已安装应用：${appReference}`);
 		const activeVersion = appRecord.installedVersions[appRecord.activeVersion];
 		if (!activeVersion) throw new Error(`已安装应用缺少激活版本：${appReference}`);
+		await this.assertVersionIntegrity(appRecord.appId, appRecord.activeVersion);
 		return {
 			appDirectory: activeVersion.installDirectory,
 			appId: appRecord.appId,
 			dataDirectory: appRecord.dataDirectory,
+			storage: appRecord.defaultInstance.storage,
 			documentGrantMap: {
 				...appRecord.grants,
 				...explicitDocumentGrantMap
@@ -337,73 +386,6 @@ var AppInstallationService = class {
 		if (!appId || Object.keys(documentGrantMap).length === 0) return;
 		await this.registryService.updateGrants(appId, documentGrantMap);
 	};
-	copyToImmutableInstallDirectory = async (params) => {
-		const { appId, appVersion, extractedDirectory, installDirectory } = params;
-		if (await this.pathExists(installDirectory)) throw new Error(`应用版本目录已存在，不能覆盖不可变版本：${appId}@${appVersion}`);
-		await mkdir(path.dirname(installDirectory), { recursive: true });
-		const stagedInstallDirectory = `${installDirectory}.staging-${randomUUID()}`;
-		try {
-			await cp(extractedDirectory, stagedInstallDirectory, { recursive: true });
-			const stagedManifest = await this.manifestService.load(stagedInstallDirectory);
-			if (stagedManifest.manifest.id !== appId || stagedManifest.manifest.version !== appVersion) throw new Error("staging manifest 与已验证 bundle 身份不一致。");
-			await rename(stagedInstallDirectory, installDirectory);
-		} catch (error) {
-			await rm(stagedInstallDirectory, {
-				recursive: true,
-				force: true
-			});
-			throw error;
-		}
-	};
-	materializeDistribution = async (params) => {
-		if (params.distributionMode !== "source") return;
-		const manifestBundle = await this.manifestService.load(params.appDirectory);
-		if (!isAppStandaloneManifestBundle(manifestBundle)) throw new Error("schema v2 组合包不允许运行安装期 build。");
-		if (manifestBundle.manifest.main.kind !== "wasi-http-component") return;
-		await this.buildService.build({
-			appDirectory: params.appDirectory,
-			install: true
-		});
-	};
-	reconcileGeneratedSiblings = async (parentDirectory, referencedPaths) => {
-		for (const entry of await this.readDirectories(parentDirectory)) {
-			const entryName = path.basename(entry);
-			const stagingMarker = ".staging-";
-			const uninstallingMarker = ".uninstalling-";
-			if (entryName.includes(stagingMarker)) {
-				await rm(entry, {
-					recursive: true,
-					force: true
-				});
-				continue;
-			}
-			const markerIndex = entryName.indexOf(uninstallingMarker);
-			if (markerIndex < 0) continue;
-			const originalPath = path.join(parentDirectory, entryName.slice(0, markerIndex));
-			if (referencedPaths.has(path.resolve(originalPath)) && !await this.pathExists(originalPath)) await rename(entry, originalPath);
-			else await rm(entry, {
-				recursive: true,
-				force: true
-			});
-		}
-	};
-	readDirectories = async (directory) => {
-		try {
-			return (await readdir(directory, { withFileTypes: true })).filter((entry) => entry.isDirectory()).map((entry) => path.join(directory, entry.name));
-		} catch (error) {
-			if (this.isMissingFileError(error)) return [];
-			throw error;
-		}
-	};
-	pathExists = async (targetPath) => {
-		try {
-			await access(targetPath);
-			return true;
-		} catch {
-			return false;
-		}
-	};
-	isMissingFileError = (error) => typeof error === "object" && error !== null && "code" in error && error.code === "ENOENT";
 };
 //#endregion
 export { AppInstallationService };