@openfairygui/backend 0.2.0-alpha.13 → 0.2.0-alpha.15

package/src/services/authoring-service.ts

@@ -1,9 +1,13 @@
-import { ProjectWriter, type FileSystem } from '@openfairygui/core/project-io';
-import { materializeUamProject, validateUamProject } from '@openfairygui/core/uam';
-import { applyUamTransactionApp, type ApplyUamTransactionAppError } from '@openfairygui/functions/uam';
-import type { CacheService } from './cache-service.js';
-import { failure, success, type BackendContext } from './context.js';
-import type { EventService } from './event-service.js';
+import { type FileSystem, type ProjectSourceFile, ProjectWriter } from '@openfairygui/core/project-io';
+import {
+	commitUamProjectSourcePaths,
+	materializeUamProject,
+	type UamProject,
+	validateUamProject,
+} from '@openfairygui/core/uam';
+import { type ApplyUamTransactionAppError, applyUamTransactionApp } from '@openfairygui/functions/uam';
+import type { BackendDiagnostic } from '../contracts.js';
+import { normalizeComparablePath, type PathPolicyViolationError, validateSaveTarget } from '../path-policy.js';
 import type {
 	ApplySessionTransactionInput,
 	BackendCapabilityUnavailableError,
@@ -15,13 +19,15 @@ import type {
 	MaterializeSessionSnapshot,
 	MaterializeValidationFailedError,
 	MaterializeWriteFailedError,
-	SaveSessionInput,
 	SavePartialFailureError,
+	SaveSessionInput,
 	SessionNotFoundError,
 	SessionStaleWriteError,
+	UamFidelityUnsupportedError,
 } from '../runtime.js';
-import type { BackendDiagnostic } from '../contracts.js';
-import { normalizeComparablePath, validateSaveTarget, type PathPolicyViolationError } from '../path-policy.js';
+import type { CacheService } from './cache-service.js';
+import { type BackendContext, failure, success } from './context.js';
+import type { EventService } from './event-service.js';
 import { createSessionNotFoundError, createStaleWriteError, toSessionSnapshot } from './session-utils.js';
 
 function createWriterFileSystem(
@@ -79,22 +85,64 @@ function createWriterFileSystem(
 		dirname(filePath: string): string {
 			return fileSystem.dirname(filePath);
 		},
+		async unlink(filePath: string): Promise<void> {
+			await trackWrite(filePath, () => fileSystem.unlink(filePath));
+		},
 	};
 }
 
+function projectAssetSourceFiles(project: UamProject): Map<string, ProjectSourceFile> {
+	const result = new Map<string, ProjectSourceFile>();
+	for (const pkg of project.packages) {
+		for (const resource of pkg.resources) {
+			if (resource.kind === 'component') continue;
+			const fileName = resource.fileName ?? resource.file ?? '';
+			if (!fileName) continue;
+			result.set(`${pkg.id}/${resource.id}`, {
+				packageName: pkg.name,
+				branch: resource.branch,
+				path: resource.path,
+				fileName,
+			});
+		}
+	}
+	return result;
+}
+
+function sourceFileKey(source: ProjectSourceFile): string {
+	return [source.branch, source.packageName, source.path, source.fileName].join('\0');
+}
+
+function recordStaleResourceSources(
+	session: Parameters<typeof toSessionSnapshot>[0],
+	previousProject: UamProject,
+	nextProject: UamProject,
+): void {
+	if (!session.fileSystem) return;
+	const previousSources = projectAssetSourceFiles(previousProject);
+	const nextSourceKeys = new Set([...projectAssetSourceFiles(nextProject).values()].map(sourceFileKey));
+	for (const source of previousSources.values()) {
+		const key = sourceFileKey(source);
+		if (!nextSourceKeys.has(key)) session.pendingStaleSourceFiles.set(key, source);
+	}
+	for (const key of nextSourceKeys) {
+		session.pendingStaleSourceFiles.delete(key);
+	}
+}
+
 function toBackendDiagnostics(error: ApplyUamTransactionAppError): BackendDiagnostic[] {
 	return error.diagnostics.length > 0
 		? error.diagnostics.map((diagnostic) => ({ ...diagnostic }))
 		: [
-			{
-				code: error.code,
-				message: error.message,
-				severity: 'error',
-				operationKind: error.operationKind,
-				opIndex: error.opIndex,
-				opId: error.opId,
-			},
-		];
+				{
+					code: error.code,
+					message: error.message,
+					severity: 'error',
+					operationKind: error.operationKind,
+					opIndex: error.opIndex,
+					opId: error.opId,
+				},
+			];
 }
 
 function createCapabilityUnavailableError(message: string): BackendCapabilityUnavailableError {
@@ -106,6 +154,17 @@ function createCapabilityUnavailableError(message: string): BackendCapabilityUna
 	};
 }
 
+function createUamFidelityUnsupportedError(
+	session: Parameters<typeof toSessionSnapshot>[0],
+): UamFidelityUnsupportedError {
+	return {
+		code: 'uam_fidelity_unsupported',
+		message: 'The source project contains formal properties that the current UAM cannot preserve.',
+		sessionId: session.sessionId,
+		canonicalPathKey: session.canonicalPathKey,
+	};
+}
+
 function validationDiagnostics(sessionProject: Parameters<typeof validateUamProject>[0]): BackendDiagnostic[] {
 	const issues = validateUamProject(sessionProject);
 	return issues.map((issue) => ({
@@ -155,12 +214,31 @@ function storageCanonicalTarget(input: NonNullable<MaterializeSessionInput['stor
 }
 
 export class AuthoringService {
+	private readonly sessionOperations = new Map<string, Promise<void>>();
+
 	public constructor(
 		private readonly context: BackendContext,
 		private readonly cacheService: CacheService,
 		private readonly eventService: EventService,
 	) {}
 
+	private async runSessionExclusive<T>(sessionId: string, operation: () => Promise<T>): Promise<T> {
+		const previous = this.sessionOperations.get(sessionId) ?? Promise.resolve();
+		let release = (): void => undefined;
+		const current = new Promise<void>((resolve) => {
+			release = resolve;
+		});
+		const tail = previous.then(() => current);
+		this.sessionOperations.set(sessionId, tail);
+		await previous;
+		try {
+			return await operation();
+		} finally {
+			release();
+			if (this.sessionOperations.get(sessionId) === tail) this.sessionOperations.delete(sessionId);
+		}
+	}
+
 	public async applyTransaction(
 		input: ApplySessionTransactionInput,
 	): Promise<
@@ -168,6 +246,17 @@ export class AuthoringService {
 			BackendSessionSnapshot,
 			SessionNotFoundError | SessionStaleWriteError | ApplyUamTransactionAppError
 		>
+	> {
+		return this.runSessionExclusive(input.sessionId, () => this.applyTransactionExclusive(input));
+	}
+
+	private async applyTransactionExclusive(
+		input: ApplySessionTransactionInput,
+	): Promise<
+		BackendResult<
+			BackendSessionSnapshot,
+			SessionNotFoundError | SessionStaleWriteError | ApplyUamTransactionAppError
+		>
 	> {
 		const startedAt = Date.now();
 		const session = this.context.sessions.get(input.sessionId);
@@ -219,6 +308,7 @@ export class AuthoringService {
 			);
 		}
 
+		recordStaleResourceSources(session, session.project, result.project);
 		session.project = result.project;
 		session.revision += 1;
 		session.dirty = true;
@@ -243,12 +333,15 @@ export class AuthoringService {
 		});
 	}
 
-	public async saveSession(input: SaveSessionInput): Promise<
+	public async saveSession(
+		input: SaveSessionInput,
+	): Promise<
 		BackendResult<
 			BackendSessionSnapshot | MaterializeSessionSnapshot,
 			| SessionNotFoundError
 			| SessionStaleWriteError
 			| SavePartialFailureError
+			| UamFidelityUnsupportedError
 			| MaterializeValidationFailedError
 			| MaterializeWriteFailedError
 			| PathPolicyViolationError
@@ -266,19 +359,36 @@ export class AuthoringService {
 				reason: 'force_save',
 			});
 		}
+		return this.runSessionExclusive(input.sessionId, () => this.saveSessionExclusive(input));
+	}
+
+	private async saveSessionExclusive(
+		input: SaveSessionInput,
+	): Promise<
+		BackendResult<
+			BackendSessionSnapshot | MaterializeSessionSnapshot,
+			| SessionNotFoundError
+			| SessionStaleWriteError
+			| SavePartialFailureError
+			| UamFidelityUnsupportedError
+			| MaterializeValidationFailedError
+			| MaterializeWriteFailedError
+			| PathPolicyViolationError
+			| InProcessLockConflictError
+			| BackendCapabilityUnavailableError
+		>
+	> {
 		const startedAt = Date.now();
 		const session = this.context.sessions.get(input.sessionId);
 		if (!session || session.closed) {
 			return failure('authoring', startedAt, createSessionNotFoundError(input.sessionId));
 		}
-		const fileSystem = input.fileSystem ?? session.fileSystem ?? this.context.fileSystem;
+		const fileSystem = session.fileSystem ?? input.fileSystem ?? this.context.fileSystem;
 		if (!fileSystem) {
 			return failure(
 				'authoring',
 				startedAt,
-				createCapabilityUnavailableError(
-					'saveSession requires an injected BackendFileSystem adapter.',
-				),
+				createCapabilityUnavailableError('saveSession requires an injected BackendFileSystem adapter.'),
 				toSessionSnapshot(session, this.context.capabilities),
 				{
 					sessionId: session.sessionId,
@@ -317,6 +427,18 @@ export class AuthoringService {
 				revision: session.revision,
 			});
 		}
+		if (session.uamFidelity === 'unsupported') {
+			return failure(
+				'authoring',
+				startedAt,
+				createUamFidelityUnsupportedError(session),
+				toSessionSnapshot(session, this.context.capabilities),
+				{
+					sessionId: session.sessionId,
+					revision: session.revision,
+				},
+			);
+		}
 
 		const committedPaths: string[] = [];
 		const failedPaths: string[] = [];
@@ -328,7 +450,12 @@ export class AuthoringService {
 		});
 		try {
 			const writer = new ProjectWriter(createWriterFileSystem(fileSystem, committedPaths, failedPaths));
-			await writer.write(materializeUamProject(session.project), session.fairyPath);
+			await writer.write(materializeUamProject(session.project), session.fairyPath, {
+				staleSourceFiles: [...session.pendingStaleSourceFiles.values()],
+			});
+			session.fileSystem ??= fileSystem;
+			session.pendingStaleSourceFiles.clear();
+			commitUamProjectSourcePaths(session.project);
 			session.lastSavedRevision = session.revision;
 			session.dirty = false;
 			const cacheEntry = this.cacheService.refreshSession(session);
@@ -380,11 +507,32 @@ export class AuthoringService {
 		}
 	}
 
-	public async materializeSession(input: MaterializeSessionInput): Promise<
+	public async materializeSession(
+		input: MaterializeSessionInput,
+	): Promise<
+		BackendResult<
+			MaterializeSessionSnapshot,
+			| SessionNotFoundError
+			| SessionStaleWriteError
+			| UamFidelityUnsupportedError
+			| MaterializeValidationFailedError
+			| MaterializeWriteFailedError
+			| PathPolicyViolationError
+			| InProcessLockConflictError
+			| BackendCapabilityUnavailableError
+		>
+	> {
+		return this.runSessionExclusive(input.sessionId, () => this.materializeSessionExclusive(input));
+	}
+
+	private async materializeSessionExclusive(
+		input: MaterializeSessionInput,
+	): Promise<
 		BackendResult<
 			MaterializeSessionSnapshot,
 			| SessionNotFoundError
 			| SessionStaleWriteError
+			| UamFidelityUnsupportedError
 			| MaterializeValidationFailedError
 			| MaterializeWriteFailedError
 			| PathPolicyViolationError
@@ -411,14 +559,13 @@ export class AuthoringService {
 		}
 
 		const storageTarget = input.storage ? storageCanonicalTarget(input.storage) : null;
-		const fileSystem = storageTarget?.fileSystem ?? input.fileSystem ?? session.fileSystem ?? this.context.fileSystem;
+		const fileSystem =
+			storageTarget?.fileSystem ?? input.fileSystem ?? session.fileSystem ?? this.context.fileSystem;
 		if (!fileSystem) {
 			return failure(
 				'authoring',
 				startedAt,
-				createCapabilityUnavailableError(
-					'materializeSession requires an injected BackendFileSystem adapter.',
-				),
+				createCapabilityUnavailableError('materializeSession requires an injected BackendFileSystem adapter.'),
 				toSessionSnapshot(session, this.context.capabilities),
 				{
 					sessionId: session.sessionId,
@@ -464,6 +611,19 @@ export class AuthoringService {
 			}
 		}
 
+		if (session.uamFidelity === 'unsupported') {
+			return failure(
+				'authoring',
+				startedAt,
+				createUamFidelityUnsupportedError(session),
+				toSessionSnapshot(session, this.context.capabilities),
+				{
+					sessionId: session.sessionId,
+					revision: session.revision,
+				},
+			);
+		}
+
 		const diagnostics = validationDiagnostics(session.project);
 		if (diagnostics.length > 0) {
 			const error: MaterializeValidationFailedError = {
@@ -474,17 +634,11 @@ export class AuthoringService {
 				issueCount: diagnostics.length,
 				diagnostics,
 			};
-			return failure(
-				'authoring',
-				startedAt,
-				error,
-				toSessionSnapshot(session, this.context.capabilities),
-				{
-					sessionId: session.sessionId,
-					revision: session.revision,
-					diagnostics,
-				},
-			);
+			return failure('authoring', startedAt, error, toSessionSnapshot(session, this.context.capabilities), {
+				sessionId: session.sessionId,
+				revision: session.revision,
+				diagnostics,
+			});
 		}
 
 		let document: ReturnType<typeof materializeUamProject>;
@@ -530,7 +684,13 @@ export class AuthoringService {
 		});
 		try {
 			const writer = new ProjectWriter(createWriterFileSystem(fileSystem, writtenPaths, failedPaths));
-			await writer.write(document, fairyPath);
+			const isSessionStorageTarget = fileSystem === session.fileSystem && fairyPath === session.fairyPath;
+			await writer.write(document, fairyPath, {
+				staleSourceFiles: isSessionStorageTarget ? [...session.pendingStaleSourceFiles.values()] : [],
+			});
+			if (isSessionStorageTarget) session.pendingStaleSourceFiles.clear();
+			if (storageTarget && !isSessionStorageTarget) session.pendingStaleSourceFiles.clear();
+			if (isSessionStorageTarget || storageTarget) commitUamProjectSourcePaths(session.project);
 			if (storageTarget) {
 				this.context.sessionsByPath.delete(session.canonicalPathKey);
 				session.fileSystem = storageTarget.fileSystem;

package/src/services/context.ts

@@ -1,3 +1,11 @@
+import {
+	BACKEND_CAPABILITY_SCHEMA_VERSION,
+	BACKEND_CONTRACT_VERSION,
+	type BackendDiagnostic,
+	type BackendMessage,
+	type BackendResponseMeta,
+	type BackendStage,
+} from '../contracts.js';
 import type {
 	BackendCacheEntry,
 	BackendCapabilities,
@@ -10,14 +18,6 @@ import type {
 	BackendSessionSnapshot,
 	BackendSuccess,
 } from '../runtime.js';
-import {
-	BACKEND_CAPABILITY_SCHEMA_VERSION,
-	BACKEND_CONTRACT_VERSION,
-	type BackendDiagnostic,
-	type BackendMessage,
-	type BackendResponseMeta,
-	type BackendStage,
-} from '../contracts.js';
 
 export interface BackendSessionState {
 	sessionId: string;
@@ -27,8 +27,11 @@ export interface BackendSessionState {
 	lockFilePath: string;
 	fileSystem?: BackendFileSystem;
 	project: import('@openfairygui/core/uam').UamProject;
+	uamFidelity: 'full' | 'unsupported';
 	revision: number;
 	lastSavedRevision: number;
+	/** Source files deferred until a successful replacement project write. */
+	pendingStaleSourceFiles: Map<string, import('@openfairygui/core/project-io').ProjectSourceFile>;
 	dirty: boolean;
 	lockHeld: boolean;
 	closed: boolean;

package/src/services/runtime-service.ts

@@ -1,20 +1,25 @@
-import { ProjectReader, type FileSystem } from '@openfairygui/core/project-io';
-import { liftDocumentToUamProject, normalizeUamProject } from '@openfairygui/core/uam';
-import { failure, success, type BackendContext, type BackendSessionState } from './context.js';
-import type { CacheService } from './cache-service.js';
-import type { EventService } from './event-service.js';
-import type { JobService } from './job-service.js';
+import { type FileSystem, ProjectReader, ProjectWriter } from '@openfairygui/core/project-io';
+import {
+	liftDocumentToUamProject,
+	materializeUamProject,
+	normalizeUamProject,
+	type UamProject,
+} from '@openfairygui/core/uam';
+import { normalizeComparablePath, resolveCanonicalProjectRoot } from '../path-policy.js';
 import type {
 	AdvisoryLockConflictError,
+	BackendCapabilityUnavailableError,
 	BackendFileHandle,
 	BackendResult,
 	BackendSessionSnapshot,
-	BackendCapabilityUnavailableError,
 	InProcessLockConflictError,
 	OpenProjectSessionInput,
 	SessionNotFoundError,
 } from '../runtime.js';
-import { normalizeComparablePath, resolveCanonicalProjectRoot } from '../path-policy.js';
+import type { CacheService } from './cache-service.js';
+import { type BackendContext, type BackendSessionState, failure, success } from './context.js';
+import type { EventService } from './event-service.js';
+import type { JobService } from './job-service.js';
 import { createSessionNotFoundError, toSessionSnapshot } from './session-utils.js';
 
 function randomId(): string {
@@ -74,6 +79,82 @@ function createProjectReaderFileSystem(fileSystem: NonNullable<BackendContext['f
 	};
 }
 
+function createCaptureFileSystem(files: Map<string, string | Uint8Array>): FileSystem {
+	const normalize = (filePath: string): string => filePath.replace(/\\/g, '/').replace(/\/+/g, '/');
+	return {
+		async readFile(filePath: string): Promise<string> {
+			const value = files.get(normalize(filePath));
+			if (typeof value !== 'string') throw new Error(`Captured text file was not found: ${filePath}`);
+			return value;
+		},
+		async readFileRaw(filePath: string): Promise<Uint8Array> {
+			const value = files.get(normalize(filePath));
+			if (!(value instanceof Uint8Array)) throw new Error(`Captured binary file was not found: ${filePath}`);
+			return value.slice();
+		},
+		async writeFile(filePath: string, content: string): Promise<void> {
+			files.set(normalize(filePath), content);
+		},
+		async writeFileRaw(filePath: string, data: Uint8Array): Promise<void> {
+			files.set(normalize(filePath), data.slice());
+		},
+		async mkdir(): Promise<void> {},
+		async readdir(): Promise<string[]> {
+			return [];
+		},
+		async exists(filePath: string): Promise<boolean> {
+			return files.has(normalize(filePath));
+		},
+		join(...paths: string[]): string {
+			return normalize(paths.filter(Boolean).join('/'));
+		},
+		dirname(filePath: string): string {
+			const normalized = normalize(filePath);
+			const separator = normalized.lastIndexOf('/');
+			return separator < 0 ? '' : normalized.slice(0, separator);
+		},
+		async unlink(filePath: string): Promise<void> {
+			files.delete(normalize(filePath));
+		},
+	};
+}
+
+function capturedFilesEqual(left: Map<string, string | Uint8Array>, right: Map<string, string | Uint8Array>): boolean {
+	if (left.size !== right.size) return false;
+	for (const [filePath, leftValue] of left) {
+		const rightValue = right.get(filePath);
+		if (typeof leftValue === 'string') {
+			if (leftValue !== rightValue) return false;
+			continue;
+		}
+		if (!(rightValue instanceof Uint8Array) || leftValue.length !== rightValue.length) return false;
+		for (let index = 0; index < leftValue.length; index += 1) {
+			if (leftValue[index] !== rightValue[index]) return false;
+		}
+	}
+	return true;
+}
+
+async function hasFullUamFidelity(
+	document: Awaited<ReturnType<ProjectReader['read']>>,
+	project: UamProject,
+): Promise<boolean> {
+	const sourceFiles = new Map<string, string | Uint8Array>();
+	const materializedFiles = new Map<string, string | Uint8Array>();
+	try {
+		await Promise.all([
+			new ProjectWriter(createCaptureFileSystem(sourceFiles)).write(document, 'Project.fairy'),
+			new ProjectWriter(createCaptureFileSystem(materializedFiles)).write(
+				materializeUamProject(project),
+				'Project.fairy',
+			),
+		]);
+	} catch {
+		return false;
+	}
+	return capturedFilesEqual(sourceFiles, materializedFiles);
+}
+
 export class RuntimeService {
 	public constructor(
 		private readonly context: BackendContext,
@@ -129,7 +210,8 @@ export class RuntimeService {
 			await advisoryLock.close();
 
 			const reader = new ProjectReader(createProjectReaderFileSystem(fileSystem));
-			const project = liftDocumentToUamProject(await reader.read(fairyPath));
+			const document = await reader.read(fairyPath, { hydrateResourceBytes: true });
+			const project = liftDocumentToUamProject(document);
 			const sessionId = randomId();
 			const session: BackendSessionState = {
 				sessionId,
@@ -139,8 +221,10 @@ export class RuntimeService {
 				lockFilePath,
 				fileSystem,
 				project,
+				uamFidelity: (await hasFullUamFidelity(document, project)) ? 'full' : 'unsupported',
 				revision: 0,
 				lastSavedRevision: 0,
+				pendingStaleSourceFiles: new Map(),
 				dirty: false,
 				lockHeld: true,
 				closed: false,
@@ -177,12 +261,14 @@ export class RuntimeService {
 		const sessionId = input.sessionId ?? randomId();
 		const storage = input.storage;
 		const memoryProjectPath = `memory://${sessionId}`;
-		const canonicalProjectPath = storage?.canonicalProjectPath
-			?? input.canonicalProjectPath
-			?? (storage ? storage.fileSystem.dirname(storage.fairyPath) || '.' : memoryProjectPath);
-		const canonicalPathKey = storage?.canonicalPathKey
-			?? input.canonicalPathKey
-			?? (storage ? normalizeComparablePath(canonicalProjectPath) : canonicalProjectPath.toLowerCase());
+		const canonicalProjectPath =
+			storage?.canonicalProjectPath ??
+			input.canonicalProjectPath ??
+			(storage ? storage.fileSystem.dirname(storage.fairyPath) || '.' : memoryProjectPath);
+		const canonicalPathKey =
+			storage?.canonicalPathKey ??
+			input.canonicalPathKey ??
+			(storage ? normalizeComparablePath(canonicalProjectPath) : canonicalProjectPath.toLowerCase());
 		const existingSessionId = this.context.sessionsByPath.get(canonicalPathKey);
 		if (existingSessionId) {
 			return failure('runtime', startedAt, {
@@ -202,8 +288,10 @@ export class RuntimeService {
 			lockFilePath: '',
 			fileSystem: storage?.fileSystem,
 			project: normalizeUamProject(input.project),
+			uamFidelity: 'full',
 			revision: 0,
 			lastSavedRevision: 0,
+			pendingStaleSourceFiles: new Map(),
 			dirty: false,
 			lockHeld: false,
 			closed: false,

package/src/services/session-utils.ts

@@ -7,13 +7,17 @@ import type {
 import type { BackendSessionState } from './context.js';
 import { cloneCapabilitiesSnapshot } from './snapshot-utils.js';
 
-export function toSessionSnapshot(session: BackendSessionState, capabilities: BackendCapabilities): BackendSessionSnapshot {
+export function toSessionSnapshot(
+	session: BackendSessionState,
+	capabilities: BackendCapabilities,
+): BackendSessionSnapshot {
 	return {
 		sessionId: session.sessionId,
 		canonicalProjectPath: session.canonicalProjectPath,
 		revision: session.revision,
 		lastSavedRevision: session.lastSavedRevision,
 		dirty: session.dirty,
+		uamFidelity: session.uamFidelity,
 		lockHeld: session.lockHeld,
 		capabilities: cloneCapabilitiesSnapshot(capabilities),
 	};

package/src/storage.ts

@@ -21,7 +21,7 @@ export interface BackendAsyncStorageAdapter {
 	stat?(filePath: string): Promise<BackendStorageStatLike>;
 	resolvePath?(filePath: string): Promise<string>;
 	openExclusive?(filePath: string): Promise<BackendFileHandle>;
-	unlink?(filePath: string): Promise<void>;
+	unlink(filePath: string): Promise<void>;
 	join?(...paths: string[]): string;
 	dirname?(filePath: string): string;
 	resolve?(...paths: string[]): string;
@@ -114,6 +114,9 @@ async function inferStat(storage: BackendAsyncStorageAdapter, filePath: string):
 export type BackendStorageFileSystem = BackendFileSystem & CoreProjectFileSystem;
 
 export function createBackendStorageFileSystem(storage: BackendAsyncStorageAdapter): BackendStorageFileSystem {
+	if (typeof storage.unlink !== 'function') {
+		throw createPathError('ENOTSUP', 'Storage adapter must provide unlink() for project resource lifecycle writes.');
+	}
 	const lockedPaths = new Set<string>();
 
 	const fileSystem: BackendStorageFileSystem = {
@@ -174,8 +177,7 @@ export function createBackendStorageFileSystem(storage: BackendAsyncStorageAdapt
 		unlink(filePath: string): Promise<void> {
 			const resolved = fileSystem.resolve(filePath);
 			lockedPaths.delete(resolved);
-			if (storage.unlink) return storage.unlink(resolved);
-			throw createPathError('ENOTSUP', 'Storage adapter does not provide unlink().');
+			return storage.unlink(resolved);
 		},
 		join(...paths: string[]): string {
 			return storage.join ? storage.join(...paths) : joinStoragePath(...paths);