@openfairygui/backend 0.2.0-alpha.3 → 0.2.0-alpha.31

package/src/services/cache-service.ts

@@ -7,7 +7,6 @@ import type {
 	GetCacheSnapshotInput,
 	SessionNotFoundError,
 } from '../runtime.js';
-import { cloneCacheEntrySnapshot } from './snapshot-utils.js';
 
 function createCacheEntry(session: BackendSessionState, valid: boolean): BackendCacheEntry {
 	return {
@@ -38,7 +37,7 @@ export class CacheService {
 		const entry = this.context.cacheBySession.get(input.sessionId);
 		return success('read', startedAt, {
 			cacheRevision: entry?.revision ?? session.revision,
-			entries: entry ? [cloneCacheEntrySnapshot(entry)] : [],
+			entries: entry ? [structuredClone(entry)] : [],
 		}, { sessionId: session.sessionId, revision: session.revision });
 	}
 

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;
@@ -25,9 +25,15 @@ export interface BackendSessionState {
 	canonicalProjectPath: string;
 	canonicalPathKey: string;
 	lockFilePath: string;
+	fileSystem?: BackendFileSystem;
 	project: import('@openfairygui/core/uam').UamProject;
+	uamFidelity: 'full' | 'unsupported';
 	revision: number;
 	lastSavedRevision: number;
+	/** Package-controlled files deferred until a successful replacement project write. */
+	pendingStaleSourceFiles: Map<string, import('@openfairygui/core/project-io').ProjectSourceFile>;
+	/** Empty resource directories deferred until a successful replacement project write. */
+	pendingStaleResourceFolders: Map<string, import('@openfairygui/core/project-io').ProjectResourceFolder>;
 	dirty: boolean;
 	lockHeld: boolean;
 	closed: boolean;

package/src/services/event-service.ts

@@ -8,7 +8,6 @@ import type {
 	GetEventsSnapshot,
 	SessionNotFoundError,
 } from '../runtime.js';
-import { cloneEventSnapshot } from './snapshot-utils.js';
 
 const DEFAULT_EVENT_RETENTION_LIMIT = 1000;
 
@@ -71,7 +70,7 @@ export class EventService {
 		const filtered = events.filter((event) => event.sequence > after);
 		const limit = input.limit === undefined ? filtered.length : Math.max(0, input.limit);
 		return success('runtime', startedAt, {
-			events: filtered.slice(0, limit).map(cloneEventSnapshot),
+			events: filtered.slice(0, limit).map((event) => structuredClone(event)),
 			oldestSequence,
 			currentSequence,
 			cursorExpired: false,

package/src/services/job-service.ts

@@ -2,7 +2,6 @@ import { failure, success, type BackendContext } from './context.js';
 import type { CacheService } from './cache-service.js';
 import type { EventService } from './event-service.js';
 import { createSessionNotFoundError } from './session-utils.js';
-import { cloneJobSnapshot } from './snapshot-utils.js';
 import type {
 	BackendJobListSnapshot,
 	BackendJobNotCancellableError,
@@ -76,7 +75,7 @@ export class JobService {
 		this.eventService.emit({ kind: 'job.created', sessionId: session.sessionId, canonicalPathKey: session.canonicalPathKey, revision: session.revision, jobId });
 		this.scheduleRefreshJob(session.sessionId, jobId);
 
-		return success('runtime', startedAt, cloneJobSnapshot(job), { sessionId: session.sessionId, revision: session.revision });
+		return success('runtime', startedAt, structuredClone(job), { sessionId: session.sessionId, revision: session.revision });
 	}
 
 	public getJob(input: GetJobInput): BackendResult<BackendJobSnapshot, SessionNotFoundError | BackendJobNotFoundError> {
@@ -92,7 +91,7 @@ export class JobService {
 				jobId: input.jobId,
 			}, undefined, { sessionId: session.sessionId, revision: session.revision });
 		}
-		return success('runtime', startedAt, cloneJobSnapshot(job), { sessionId: session.sessionId, revision: session.revision });
+		return success('runtime', startedAt, structuredClone(job), { sessionId: session.sessionId, revision: session.revision });
 	}
 
 	public listJobs(input: ListJobsInput): BackendResult<BackendJobListSnapshot, SessionNotFoundError> {
@@ -107,7 +106,7 @@ export class JobService {
 			else jobs = jobs.filter((job) => job.status === input.status);
 		}
 		if (input.limit !== undefined) jobs = jobs.slice(0, Math.max(0, input.limit));
-		return success('runtime', startedAt, { jobs: jobs.map(cloneJobSnapshot) }, { sessionId: session.sessionId, revision: session.revision });
+		return success('runtime', startedAt, { jobs: jobs.map((job) => structuredClone(job)) }, { sessionId: session.sessionId, revision: session.revision });
 	}
 
 	public cancelJob(input: CancelJobInput): BackendResult<BackendJobSnapshot, SessionNotFoundError | BackendJobNotFoundError | BackendJobNotCancellableError> {
@@ -135,7 +134,7 @@ export class JobService {
 		this.cancellationRequests.add(job.jobId);
 		this.eventService.emit({ kind: 'job.cancelRequested', sessionId: input.sessionId, canonicalPathKey: session.canonicalPathKey, revision: session.revision, jobId: job.jobId });
 		const cancelled = this.cancelRefreshJob(session.sessionId, job);
-		return success('runtime', startedAt, cloneJobSnapshot(cancelled), { sessionId: session.sessionId, revision: session.revision });
+		return success('runtime', startedAt, structuredClone(cancelled), { sessionId: session.sessionId, revision: session.revision });
 	}
 
 	public removeSession(sessionId: string): void {

package/src/services/read-service.ts

@@ -1,13 +1,12 @@
 import { failure, success, type BackendContext } from './context.js';
 import type { BackendCapabilities, BackendResult, BackendSessionSnapshot, SessionNotFoundError } from '../runtime.js';
 import { createSessionNotFoundError, toSessionSnapshot } from './session-utils.js';
-import { cloneCapabilitiesSnapshot } from './snapshot-utils.js';
 
 export class ReadService {
 	public constructor(private readonly context: BackendContext) {}
 
 	public getCapabilities(): BackendResult<BackendCapabilities> {
-		return success('read', Date.now(), cloneCapabilitiesSnapshot(this.context.capabilities));
+		return success('read', Date.now(), structuredClone(this.context.capabilities));
 	}
 
 	public getSession(input: { sessionId: string }): BackendResult<BackendSessionSnapshot, SessionNotFoundError> {

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 { 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,94 @@ function createProjectReaderFileSystem(fileSystem: NonNullable<BackendContext['f
 	};
 }
 
+function createCaptureFileSystem(
+	files: Map<string, string | Uint8Array>,
+	directories: Set<string>,
+): 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(dirPath: string): Promise<void> {
+			directories.add(normalize(dirPath));
+		},
+		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;
+}
+
+function capturedDirectoriesEqual(left: Set<string>, right: Set<string>): boolean {
+	return left.size === right.size && [...left].every((directory) => right.has(directory));
+}
+
+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>();
+	const sourceDirectories = new Set<string>();
+	const materializedDirectories = new Set<string>();
+	try {
+		await Promise.all([
+			new ProjectWriter(createCaptureFileSystem(sourceFiles, sourceDirectories)).write(document, 'Project.fairy'),
+			new ProjectWriter(createCaptureFileSystem(materializedFiles, materializedDirectories)).write(
+				materializeUamProject(project),
+				'Project.fairy',
+			),
+		]);
+	} catch {
+		return false;
+	}
+	return capturedFilesEqual(sourceFiles, materializedFiles)
+		&& capturedDirectoriesEqual(sourceDirectories, materializedDirectories);
+}
+
 export class RuntimeService {
 	public constructor(
 		private readonly context: BackendContext,
@@ -129,7 +222,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,
@@ -137,9 +231,13 @@ export class RuntimeService {
 				canonicalProjectPath,
 				canonicalPathKey,
 				lockFilePath,
+				fileSystem,
 				project,
+				uamFidelity: (await hasFullUamFidelity(document, project)) ? 'full' : 'unsupported',
 				revision: 0,
 				lastSavedRevision: 0,
+				pendingStaleSourceFiles: new Map(),
+				pendingStaleResourceFolders: new Map(),
 				dirty: false,
 				lockHeld: true,
 				closed: false,
@@ -174,8 +272,16 @@ export class RuntimeService {
 	public openProjectSession(input: OpenProjectSessionInput): BackendResult<BackendSessionSnapshot> {
 		const startedAt = Date.now();
 		const sessionId = input.sessionId ?? randomId();
-		const canonicalProjectPath = input.canonicalProjectPath ?? `memory://${sessionId}`;
-		const canonicalPathKey = input.canonicalPathKey ?? canonicalProjectPath.toLowerCase();
+		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 existingSessionId = this.context.sessionsByPath.get(canonicalPathKey);
 		if (existingSessionId) {
 			return failure('runtime', startedAt, {
@@ -189,13 +295,17 @@ export class RuntimeService {
 
 		const session: BackendSessionState = {
 			sessionId,
-			fairyPath: canonicalProjectPath,
+			fairyPath: storage?.fairyPath ?? canonicalProjectPath,
 			canonicalProjectPath,
 			canonicalPathKey,
 			lockFilePath: '',
+			fileSystem: storage?.fileSystem,
 			project: normalizeUamProject(input.project),
+			uamFidelity: 'full',
 			revision: 0,
 			lastSavedRevision: 0,
+			pendingStaleSourceFiles: new Map(),
+			pendingStaleResourceFolders: new Map(),
 			dirty: false,
 			lockHeld: false,
 			closed: false,

package/src/services/session-project-writer.ts

@@ -0,0 +1,67 @@
+import type { Document } from '@openfairygui/core';
+import { type FileSystem, type ProjectSourceFile, ProjectWriter } from '@openfairygui/core/project-io';
+import type { BackendFileSystem } from '../runtime.js';
+
+function createWriterFileSystem(
+	fileSystem: BackendFileSystem,
+	writtenPaths: string[],
+	failedPaths: string[],
+): FileSystem {
+	async function trackWrite<T>(targetPath: string, write: () => Promise<T>): Promise<T> {
+		try {
+			const result = await write();
+			writtenPaths.push(targetPath);
+			return result;
+		} catch (error) {
+			failedPaths.push(targetPath);
+			throw error;
+		}
+	}
+
+	return {
+		readFile: (path) => fileSystem.readFile(path),
+		readFileRaw: (path) => fileSystem.readFileRaw(path),
+		writeFile: (path, content) =>
+			trackWrite(path, async () => {
+				await fileSystem.mkdir(fileSystem.dirname(path), { recursive: true });
+				await fileSystem.writeFile(path, content);
+			}),
+		writeFileRaw: (path, data) =>
+			trackWrite(path, async () => {
+				await fileSystem.mkdir(fileSystem.dirname(path), { recursive: true });
+				await fileSystem.writeFileRaw(path, data);
+			}),
+		mkdir: (path) => fileSystem.mkdir(path, { recursive: true }),
+		readdir: (path) => fileSystem.readdir(path),
+		async exists(path): Promise<boolean> {
+			try {
+				await fileSystem.stat(path);
+				return true;
+			} catch {
+				return false;
+			}
+		},
+		join: (...paths) => fileSystem.join(...paths),
+		dirname: (path) => fileSystem.dirname(path),
+		unlink: (path) => trackWrite(path, () => fileSystem.unlink(path)),
+		rmdir: (path) => trackWrite(path, () => fileSystem.rmdir(path)),
+	};
+}
+
+export async function writeSessionProject(input: {
+	fileSystem: BackendFileSystem;
+	document: Document;
+	fairyPath: string;
+	staleSourceFiles: ProjectSourceFile[];
+	staleResourceFolders: import('@openfairygui/core/project-io').ProjectResourceFolder[];
+	writtenPaths: string[];
+	failedPaths: string[];
+}): Promise<void> {
+	const writer = new ProjectWriter(
+		createWriterFileSystem(input.fileSystem, input.writtenPaths, input.failedPaths),
+	);
+	await writer.write(input.document, input.fairyPath, {
+		staleSourceFiles: input.staleSourceFiles,
+		staleResourceFolders: input.staleResourceFolders,
+	});
+}

package/src/services/session-utils.ts

@@ -5,17 +5,20 @@ import type {
 	SessionStaleWriteError,
 } from '../runtime.js';
 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),
+		capabilities: structuredClone(capabilities),
 	};
 }
 

package/src/storage.ts

@@ -0,0 +1,201 @@
+import type { FileSystem as CoreProjectFileSystem } from '@openfairygui/core/project-io';
+import type { BackendFileHandle, BackendFileStat, BackendFileSystem } from './runtime.js';
+
+type StorageStatKind = 'file' | 'directory';
+
+export interface BackendStorageStatLike {
+	kind?: StorageStatKind;
+	type?: StorageStatKind;
+	isFile?(): boolean;
+	isDirectory?(): boolean;
+}
+
+export interface BackendAsyncStorageAdapter {
+	readFile(filePath: string): Promise<string>;
+	readFileRaw(filePath: string): Promise<Uint8Array>;
+	writeFile(filePath: string, content: string): Promise<void>;
+	writeFileRaw(filePath: string, data: Uint8Array): Promise<void>;
+	mkdir(dirPath: string, options?: { recursive?: boolean }): Promise<void>;
+	readdir(dirPath: string): Promise<string[]>;
+	exists?(filePath: string): Promise<boolean>;
+	stat?(filePath: string): Promise<BackendStorageStatLike>;
+	resolvePath?(filePath: string): Promise<string>;
+	openExclusive?(filePath: string): Promise<BackendFileHandle>;
+	unlink(filePath: string): Promise<void>;
+	rmdir(dirPath: string): Promise<void>;
+	join?(...paths: string[]): string;
+	dirname?(filePath: string): string;
+	resolve?(...paths: string[]): string;
+}
+
+class StorageFileStat implements BackendFileStat {
+	public constructor(private readonly kind: StorageStatKind) {}
+
+	public isFile(): boolean {
+		return this.kind === 'file';
+	}
+
+	public isDirectory(): boolean {
+		return this.kind === 'directory';
+	}
+}
+
+function createPathError(code: string, message: string): Error & { code: string } {
+	const error = new Error(message) as Error & { code: string };
+	error.code = code;
+	return error;
+}
+
+function normalizeStoragePath(value: string): string {
+	const normalized = value.replace(/\\/g, '/').replace(/\/+/g, '/');
+	const absolute = normalized.startsWith('/');
+	const rawSegments = normalized.split('/').filter((segment) => segment.length > 0);
+	const segments: string[] = [];
+
+	for (const segment of rawSegments) {
+		if (segment === '.') continue;
+		if (segment === '..') {
+			if (segments.length > 0) segments.pop();
+			continue;
+		}
+		segments.push(segment);
+	}
+
+	const joined = segments.join('/');
+	if (absolute) return joined ? `/${joined}` : '/';
+	return joined || '.';
+}
+
+function joinStoragePath(...paths: string[]): string {
+	return normalizeStoragePath(paths.filter((part) => part.length > 0).join('/'));
+}
+
+function dirnameStoragePath(filePath: string): string {
+	const normalized = normalizeStoragePath(filePath);
+	if (normalized === '/' || normalized === '.') return '.';
+	const absolute = normalized.startsWith('/');
+	const parts = normalized.split('/').filter((part) => part.length > 0);
+	parts.pop();
+	if (parts.length === 0) return absolute ? '/' : '.';
+	return `${absolute ? '/' : ''}${parts.join('/')}`;
+}
+
+function statFromLike(stat: BackendStorageStatLike): BackendFileStat {
+	if (typeof stat.isFile === 'function' && typeof stat.isDirectory === 'function') {
+		return stat as BackendFileStat;
+	}
+	const kind = stat.kind ?? stat.type;
+	if (kind === 'file' || kind === 'directory') return new StorageFileStat(kind);
+	throw createPathError('EINVAL', 'Storage stat must provide kind/type or isFile()/isDirectory().');
+}
+
+async function inferStat(storage: BackendAsyncStorageAdapter, filePath: string): Promise<BackendFileStat> {
+	if (storage.stat) return statFromLike(await storage.stat(filePath));
+
+	try {
+		await storage.readdir(filePath);
+		return new StorageFileStat('directory');
+	} catch {
+		// Try file probes below.
+	}
+
+	try {
+		await storage.readFileRaw(filePath);
+		return new StorageFileStat('file');
+	} catch {
+		try {
+			await storage.readFile(filePath);
+			return new StorageFileStat('file');
+		} catch {
+			throw createPathError('ENOENT', `Storage path not found: ${filePath}`);
+		}
+	}
+}
+
+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.');
+	}
+	if (typeof storage.rmdir !== 'function') {
+		throw createPathError('ENOTSUP', 'Storage adapter must provide rmdir() for project resource folder lifecycle writes.');
+	}
+	const lockedPaths = new Set<string>();
+
+	const fileSystem: BackendStorageFileSystem = {
+		stat(filePath: string): Promise<BackendFileStat> {
+			return inferStat(storage, fileSystem.resolve(filePath));
+		},
+		readdir(dirPath: string): Promise<string[]> {
+			return storage.readdir(fileSystem.resolve(dirPath));
+		},
+		readFile(filePath: string): Promise<string> {
+			return storage.readFile(fileSystem.resolve(filePath));
+		},
+		readFileRaw(filePath: string): Promise<Uint8Array> {
+			return storage.readFileRaw(fileSystem.resolve(filePath));
+		},
+		writeFile(filePath: string, content: string): Promise<void> {
+			return storage.writeFile(fileSystem.resolve(filePath), content);
+		},
+		writeFileRaw(filePath: string, data: Uint8Array): Promise<void> {
+			return storage.writeFileRaw(fileSystem.resolve(filePath), data);
+		},
+		mkdir(dirPath: string, options?: { recursive?: boolean }): Promise<void> {
+			return storage.mkdir(fileSystem.resolve(dirPath), options);
+		},
+		async exists(filePath: string): Promise<boolean> {
+			if (storage.exists) return storage.exists(fileSystem.resolve(filePath));
+			try {
+				await fileSystem.stat(filePath);
+				return true;
+			} catch {
+				return false;
+			}
+		},
+		resolvePath(filePath: string): Promise<string> {
+			const resolved = fileSystem.resolve(filePath);
+			return storage.resolvePath ? storage.resolvePath(resolved) : Promise.resolve(resolved);
+		},
+		async openExclusive(filePath: string): Promise<BackendFileHandle> {
+			const resolved = fileSystem.resolve(filePath);
+			if (storage.openExclusive) return storage.openExclusive(resolved);
+			if (lockedPaths.has(resolved) || await fileSystem.exists(resolved)) {
+				throw createPathError('EEXIST', `Storage path already exists: ${resolved}`);
+			}
+			lockedPaths.add(resolved);
+			let closed = false;
+			return {
+				async writeFile(content: string): Promise<void> {
+					if (closed) throw createPathError('EBADF', `Storage lock handle is closed: ${resolved}`);
+					await fileSystem.mkdir(fileSystem.dirname(resolved), { recursive: true });
+					await storage.writeFile(resolved, content);
+				},
+				async close(): Promise<void> {
+					closed = true;
+					lockedPaths.delete(resolved);
+				},
+			};
+		},
+		unlink(filePath: string): Promise<void> {
+			const resolved = fileSystem.resolve(filePath);
+			lockedPaths.delete(resolved);
+			return storage.unlink(resolved);
+		},
+		rmdir(dirPath: string): Promise<void> {
+			return storage.rmdir(fileSystem.resolve(dirPath));
+		},
+		join(...paths: string[]): string {
+			return storage.join ? storage.join(...paths) : joinStoragePath(...paths);
+		},
+		dirname(filePath: string): string {
+			return storage.dirname ? storage.dirname(filePath) : dirnameStoragePath(filePath);
+		},
+		resolve(...paths: string[]): string {
+			return storage.resolve ? storage.resolve(...paths) : joinStoragePath(...paths);
+		},
+	};
+
+	return fileSystem;
+}

package/src/services/snapshot-utils.ts

@@ -1,43 +0,0 @@
-import type {
-	BackendCacheEntry,
-	BackendCapabilities,
-	BackendEvent,
-	BackendJobSnapshot,
-} from '../runtime.js';
-
-function cloneJsonValue<T>(value: T): T {
-	if (value === undefined || value === null) return value;
-	return JSON.parse(JSON.stringify(value)) as T;
-}
-
-export function cloneEventSnapshot(event: BackendEvent): BackendEvent {
-	return {
-		...event,
-		diagnostics: event.diagnostics.map((diagnostic) => ({ ...diagnostic })),
-		payload: cloneJsonValue(event.payload),
-	};
-}
-
-export function cloneJobSnapshot(job: BackendJobSnapshot): BackendJobSnapshot {
-	return {
-		...job,
-		diagnostics: job.diagnostics.map((diagnostic) => ({ ...diagnostic })),
-		progress: job.progress ? { ...job.progress } : undefined,
-		result: cloneJsonValue(job.result),
-		error: cloneJsonValue(job.error),
-	};
-}
-
-export function cloneCacheEntrySnapshot(entry: BackendCacheEntry): BackendCacheEntry {
-	return {
-		...entry,
-		summary: {
-			...entry.summary,
-			diagnostics: entry.summary.diagnostics.map((diagnostic) => ({ ...diagnostic })),
-		},
-	};
-}
-
-export function cloneCapabilitiesSnapshot(capabilities: BackendCapabilities): BackendCapabilities {
-	return cloneJsonValue(capabilities);
-}