@openfairygui/backend 0.2.0-alpha.6 → 0.2.0-alpha.8

package/dist/{runtime-CqARWlcn.mjs → runtime-DFatY9W0.mjs}

@@ -1,4 +1,4 @@
-import { UAM_SUPPORTED_MATERIALIZATION_SCOPE, UAM_SUPPORTED_TRANSACTION_SCOPE, liftDocumentToUamProject, materializeUamProject, normalizeUamProject } from "@openfairygui/core/uam";
+import { UAM_SUPPORTED_MATERIALIZATION_SCOPE, UAM_SUPPORTED_TRANSACTION_SCOPE, liftDocumentToUamProject, materializeUamProject, normalizeUamProject, validateUamProject } from "@openfairygui/core/uam";
 import { ProjectReader, ProjectWriter } from "@openfairygui/core/project-io";
 import { applyUamTransactionApp } from "@openfairygui/functions/uam";
 //#region src/contracts.ts
@@ -264,6 +264,44 @@ function toBackendDiagnostics(error) {
 		opId: error.opId
 	}];
 }
+function createCapabilityUnavailableError$1(message) {
+	return {
+		code: "capability_unavailable",
+		message,
+		capability: "fileSystem",
+		requiredAdapter: "BackendFileSystem"
+	};
+}
+function validationDiagnostics(sessionProject) {
+	return validateUamProject(sessionProject).map((issue) => ({
+		code: "materialize_validation_failed",
+		message: issue.message,
+		severity: "error",
+		path: issue.path,
+		operationKind: "materializeSession"
+	}));
+}
+function toMaterializeSnapshot(session, capabilities, input) {
+	return {
+		...toSessionSnapshot(session, capabilities),
+		mode: "fullProject",
+		reason: input.reason,
+		materializeRevision: session.revision,
+		saveRevision: session.lastSavedRevision,
+		writtenPaths: [...input.writtenPaths],
+		skippedPaths: [...input.skippedPaths],
+		diagnostics: input.diagnostics.map((diagnostic) => ({ ...diagnostic }))
+	};
+}
+function storageCanonicalTarget(input) {
+	const canonicalProjectPath = input.canonicalProjectPath ?? (input.fileSystem.dirname(input.fairyPath) || ".");
+	return {
+		fileSystem: input.fileSystem,
+		fairyPath: input.fairyPath,
+		canonicalProjectPath,
+		canonicalPathKey: input.canonicalPathKey ?? normalizeComparablePath(canonicalProjectPath)
+	};
+}
 var AuthoringService = class {
 	constructor(context, cacheService, eventService) {
 		this.context = context;
@@ -328,15 +366,19 @@ var AuthoringService = class {
 		});
 	}
 	async saveSession(input) {
+		if (input.force === true || input.mode === "materializeCleanSession") return this.materializeSession({
+			sessionId: input.sessionId,
+			expectedRevision: input.expectedRevision,
+			targetPath: input.targetPath,
+			fileSystem: input.fileSystem,
+			mode: "fullProject",
+			reason: "force_save"
+		});
 		const startedAt = Date.now();
 		const session = this.context.sessions.get(input.sessionId);
 		if (!session || session.closed) return failure("authoring", startedAt, createSessionNotFoundError(input.sessionId));
-		if (!this.context.fileSystem) return failure("authoring", startedAt, {
-			code: "capability_unavailable",
-			message: "saveSession requires an injected BackendFileSystem adapter.",
-			capability: "fileSystem",
-			requiredAdapter: "BackendFileSystem"
-		}, toSessionSnapshot(session, this.context.capabilities), {
+		const fileSystem = input.fileSystem ?? session.fileSystem ?? this.context.fileSystem;
+		if (!fileSystem) return failure("authoring", startedAt, createCapabilityUnavailableError$1("saveSession requires an injected BackendFileSystem adapter."), toSessionSnapshot(session, this.context.capabilities), {
 			sessionId: session.sessionId,
 			revision: session.revision
 		});
@@ -344,7 +386,6 @@ var AuthoringService = class {
 			sessionId: session.sessionId,
 			revision: session.revision
 		});
-		const fileSystem = this.context.fileSystem;
 		const targetViolation = await validateSaveTarget(fileSystem, session.fairyPath, input.targetPath);
 		if (targetViolation) return failure("authoring", startedAt, targetViolation, toSessionSnapshot(session, this.context.capabilities), {
 			sessionId: session.sessionId,
@@ -408,6 +449,154 @@ var AuthoringService = class {
 			});
 		}
 	}
+	async materializeSession(input) {
+		const startedAt = Date.now();
+		const session = this.context.sessions.get(input.sessionId);
+		if (!session || session.closed) return failure("authoring", startedAt, createSessionNotFoundError(input.sessionId));
+		if (input.expectedRevision !== void 0 && input.expectedRevision !== session.revision) return failure("authoring", startedAt, createStaleWriteError(session, input.expectedRevision), toSessionSnapshot(session, this.context.capabilities), {
+			sessionId: session.sessionId,
+			revision: session.revision
+		});
+		const storageTarget = input.storage ? storageCanonicalTarget(input.storage) : null;
+		const fileSystem = storageTarget?.fileSystem ?? input.fileSystem ?? session.fileSystem ?? this.context.fileSystem;
+		if (!fileSystem) return failure("authoring", startedAt, createCapabilityUnavailableError$1("materializeSession requires an injected BackendFileSystem adapter."), toSessionSnapshot(session, this.context.capabilities), {
+			sessionId: session.sessionId,
+			revision: session.revision
+		});
+		const fairyPath = storageTarget?.fairyPath ?? session.fairyPath;
+		const targetViolation = await validateSaveTarget(fileSystem, fairyPath, input.targetPath);
+		if (targetViolation) return failure("authoring", startedAt, targetViolation, toSessionSnapshot(session, this.context.capabilities), {
+			sessionId: session.sessionId,
+			revision: session.revision
+		});
+		if (storageTarget) {
+			const holderSessionId = this.context.sessionsByPath.get(storageTarget.canonicalPathKey);
+			if (holderSessionId && holderSessionId !== session.sessionId) return failure("authoring", startedAt, {
+				code: "lock_conflict",
+				kind: "in_process_session_exists",
+				message: `Project is already open in this backend runtime: ${storageTarget.canonicalProjectPath}`,
+				canonicalPathKey: storageTarget.canonicalPathKey,
+				holderSessionId
+			}, toSessionSnapshot(session, this.context.capabilities), {
+				sessionId: session.sessionId,
+				revision: session.revision
+			});
+		}
+		const diagnostics = validationDiagnostics(session.project);
+		if (diagnostics.length > 0) return failure("authoring", startedAt, {
+			code: "materialize_validation_failed",
+			message: `UAM materialize validation failed with ${diagnostics.length} issue(s).`,
+			sessionId: session.sessionId,
+			canonicalPathKey: session.canonicalPathKey,
+			issueCount: diagnostics.length,
+			diagnostics
+		}, toSessionSnapshot(session, this.context.capabilities), {
+			sessionId: session.sessionId,
+			revision: session.revision,
+			diagnostics
+		});
+		let document;
+		try {
+			document = materializeUamProject(session.project);
+		} catch (error) {
+			const diagnosticsFromError = [{
+				code: "materialize_validation_failed",
+				message: error instanceof Error ? error.message : String(error),
+				severity: "error",
+				operationKind: "materializeSession"
+			}];
+			return failure("authoring", startedAt, {
+				code: "materialize_validation_failed",
+				message: error instanceof Error ? error.message : String(error),
+				sessionId: session.sessionId,
+				canonicalPathKey: session.canonicalPathKey,
+				issueCount: diagnosticsFromError.length,
+				diagnostics: diagnosticsFromError
+			}, toSessionSnapshot(session, this.context.capabilities), {
+				sessionId: session.sessionId,
+				revision: session.revision,
+				diagnostics: diagnosticsFromError
+			});
+		}
+		const writtenPaths = [];
+		const failedPaths = [];
+		const skippedPaths = [];
+		this.eventService.emit({
+			kind: "save.started",
+			sessionId: session.sessionId,
+			canonicalPathKey: storageTarget?.canonicalPathKey ?? session.canonicalPathKey,
+			revision: session.revision
+		});
+		try {
+			await new ProjectWriter(createWriterFileSystem(fileSystem, writtenPaths, failedPaths)).write(document, fairyPath);
+			if (storageTarget) {
+				this.context.sessionsByPath.delete(session.canonicalPathKey);
+				session.fileSystem = storageTarget.fileSystem;
+				session.fairyPath = storageTarget.fairyPath;
+				session.canonicalProjectPath = storageTarget.canonicalProjectPath;
+				session.canonicalPathKey = storageTarget.canonicalPathKey;
+				this.context.sessionsByPath.set(session.canonicalPathKey, session.sessionId);
+			}
+			session.lastSavedRevision = session.revision;
+			session.dirty = false;
+			const cacheEntry = this.cacheService.refreshSession(session);
+			this.eventService.emit({
+				kind: "save.completed",
+				sessionId: session.sessionId,
+				canonicalPathKey: session.canonicalPathKey,
+				revision: session.revision
+			});
+			this.eventService.emit({
+				kind: "cache.updated",
+				sessionId: session.sessionId,
+				canonicalPathKey: session.canonicalPathKey,
+				revision: session.revision,
+				cacheRevision: cacheEntry.revision
+			});
+			return success("authoring", startedAt, toMaterializeSnapshot(session, this.context.capabilities, {
+				reason: input.reason,
+				writtenPaths,
+				skippedPaths,
+				diagnostics: []
+			}), {
+				sessionId: session.sessionId,
+				revision: session.revision
+			});
+		} catch (error) {
+			const diagnosticsFromError = [{
+				code: "write_failed",
+				message: error instanceof Error ? error.message : String(error),
+				severity: "error",
+				path: failedPaths[0],
+				operationKind: "materializeSession"
+			}];
+			this.cacheService.invalidateSession(session);
+			this.eventService.emit({
+				kind: "save.failed",
+				sessionId: session.sessionId,
+				canonicalPathKey: session.canonicalPathKey,
+				revision: session.revision,
+				diagnostics: diagnosticsFromError
+			});
+			return failure("authoring", startedAt, {
+				code: "write_failed",
+				message: error instanceof Error ? error.message : String(error),
+				sessionId: session.sessionId,
+				canonicalPathKey: session.canonicalPathKey,
+				attemptedRevision: session.revision,
+				lastSavedRevision: session.lastSavedRevision,
+				writtenPaths,
+				failedPaths,
+				skippedPaths,
+				diagnostics: diagnosticsFromError,
+				diskMayBePartiallyUpdated: true
+			}, toSessionSnapshot(session, this.context.capabilities), {
+				sessionId: session.sessionId,
+				revision: session.revision,
+				diagnostics: diagnosticsFromError
+			});
+		}
+	}
 };
 //#endregion
 //#region src/services/cache-service.ts
@@ -908,6 +1097,7 @@ var RuntimeService = class {
 				canonicalProjectPath,
 				canonicalPathKey,
 				lockFilePath,
+				fileSystem,
 				project,
 				revision: 0,
 				lastSavedRevision: 0,
@@ -946,8 +1136,10 @@ var RuntimeService = class {
 	openProjectSession(input) {
 		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, {
 			code: "lock_conflict",
@@ -958,10 +1150,11 @@ var RuntimeService = class {
 		});
 		const session = {
 			sessionId,
-			fairyPath: canonicalProjectPath,
+			fairyPath: storage?.fairyPath ?? canonicalProjectPath,
 			canonicalProjectPath,
 			canonicalPathKey,
 			lockFilePath: "",
+			fileSystem: storage?.fileSystem,
 			project: normalizeUamProject(input.project),
 			revision: 0,
 			lastSavedRevision: 0,
@@ -1025,6 +1218,7 @@ const BACKEND_METHODS = [
 	"getSession",
 	"applyTransaction",
 	"saveSession",
+	"materializeSession",
 	"closeSession",
 	"getEvents",
 	"getJob",
@@ -1073,7 +1267,21 @@ function createCapabilities() {
 			adapters: {
 				fileSystem: {
 					injected: true,
-					requiredFor: ["openSession", "saveSession"]
+					requiredFor: [
+						"openSession",
+						"saveSession",
+						"materializeSession"
+					]
+				},
+				projectStorage: {
+					injected: true,
+					browserSafe: true,
+					requiredFor: [
+						"openProjectSession.writeback",
+						"saveSession",
+						"materializeSession"
+					],
+					adapterFactory: "createBackendStorageFileSystem"
 				},
 				host: {
 					injected: true,
@@ -1180,6 +1388,9 @@ var BackendRuntime = class {
 	async saveSession(input) {
 		return this.authoringService.saveSession(input);
 	}
+	async materializeSession(input) {
+		return this.authoringService.materializeSession(input);
+	}
 	async closeSession(input) {
 		return this.runtimeService.closeSession(input);
 	}

package/dist/{runtime--ytGfQCF.cjs → runtime-GKzsXJdO.cjs}

@@ -265,6 +265,44 @@ function toBackendDiagnostics(error) {
 		opId: error.opId
 	}];
 }
+function createCapabilityUnavailableError$1(message) {
+	return {
+		code: "capability_unavailable",
+		message,
+		capability: "fileSystem",
+		requiredAdapter: "BackendFileSystem"
+	};
+}
+function validationDiagnostics(sessionProject) {
+	return (0, _openfairygui_core_uam.validateUamProject)(sessionProject).map((issue) => ({
+		code: "materialize_validation_failed",
+		message: issue.message,
+		severity: "error",
+		path: issue.path,
+		operationKind: "materializeSession"
+	}));
+}
+function toMaterializeSnapshot(session, capabilities, input) {
+	return {
+		...toSessionSnapshot(session, capabilities),
+		mode: "fullProject",
+		reason: input.reason,
+		materializeRevision: session.revision,
+		saveRevision: session.lastSavedRevision,
+		writtenPaths: [...input.writtenPaths],
+		skippedPaths: [...input.skippedPaths],
+		diagnostics: input.diagnostics.map((diagnostic) => ({ ...diagnostic }))
+	};
+}
+function storageCanonicalTarget(input) {
+	const canonicalProjectPath = input.canonicalProjectPath ?? (input.fileSystem.dirname(input.fairyPath) || ".");
+	return {
+		fileSystem: input.fileSystem,
+		fairyPath: input.fairyPath,
+		canonicalProjectPath,
+		canonicalPathKey: input.canonicalPathKey ?? normalizeComparablePath(canonicalProjectPath)
+	};
+}
 var AuthoringService = class {
 	constructor(context, cacheService, eventService) {
 		this.context = context;
@@ -329,15 +367,19 @@ var AuthoringService = class {
 		});
 	}
 	async saveSession(input) {
+		if (input.force === true || input.mode === "materializeCleanSession") return this.materializeSession({
+			sessionId: input.sessionId,
+			expectedRevision: input.expectedRevision,
+			targetPath: input.targetPath,
+			fileSystem: input.fileSystem,
+			mode: "fullProject",
+			reason: "force_save"
+		});
 		const startedAt = Date.now();
 		const session = this.context.sessions.get(input.sessionId);
 		if (!session || session.closed) return failure("authoring", startedAt, createSessionNotFoundError(input.sessionId));
-		if (!this.context.fileSystem) return failure("authoring", startedAt, {
-			code: "capability_unavailable",
-			message: "saveSession requires an injected BackendFileSystem adapter.",
-			capability: "fileSystem",
-			requiredAdapter: "BackendFileSystem"
-		}, toSessionSnapshot(session, this.context.capabilities), {
+		const fileSystem = input.fileSystem ?? session.fileSystem ?? this.context.fileSystem;
+		if (!fileSystem) return failure("authoring", startedAt, createCapabilityUnavailableError$1("saveSession requires an injected BackendFileSystem adapter."), toSessionSnapshot(session, this.context.capabilities), {
 			sessionId: session.sessionId,
 			revision: session.revision
 		});
@@ -345,7 +387,6 @@ var AuthoringService = class {
 			sessionId: session.sessionId,
 			revision: session.revision
 		});
-		const fileSystem = this.context.fileSystem;
 		const targetViolation = await validateSaveTarget(fileSystem, session.fairyPath, input.targetPath);
 		if (targetViolation) return failure("authoring", startedAt, targetViolation, toSessionSnapshot(session, this.context.capabilities), {
 			sessionId: session.sessionId,
@@ -409,6 +450,154 @@ var AuthoringService = class {
 			});
 		}
 	}
+	async materializeSession(input) {
+		const startedAt = Date.now();
+		const session = this.context.sessions.get(input.sessionId);
+		if (!session || session.closed) return failure("authoring", startedAt, createSessionNotFoundError(input.sessionId));
+		if (input.expectedRevision !== void 0 && input.expectedRevision !== session.revision) return failure("authoring", startedAt, createStaleWriteError(session, input.expectedRevision), toSessionSnapshot(session, this.context.capabilities), {
+			sessionId: session.sessionId,
+			revision: session.revision
+		});
+		const storageTarget = input.storage ? storageCanonicalTarget(input.storage) : null;
+		const fileSystem = storageTarget?.fileSystem ?? input.fileSystem ?? session.fileSystem ?? this.context.fileSystem;
+		if (!fileSystem) return failure("authoring", startedAt, createCapabilityUnavailableError$1("materializeSession requires an injected BackendFileSystem adapter."), toSessionSnapshot(session, this.context.capabilities), {
+			sessionId: session.sessionId,
+			revision: session.revision
+		});
+		const fairyPath = storageTarget?.fairyPath ?? session.fairyPath;
+		const targetViolation = await validateSaveTarget(fileSystem, fairyPath, input.targetPath);
+		if (targetViolation) return failure("authoring", startedAt, targetViolation, toSessionSnapshot(session, this.context.capabilities), {
+			sessionId: session.sessionId,
+			revision: session.revision
+		});
+		if (storageTarget) {
+			const holderSessionId = this.context.sessionsByPath.get(storageTarget.canonicalPathKey);
+			if (holderSessionId && holderSessionId !== session.sessionId) return failure("authoring", startedAt, {
+				code: "lock_conflict",
+				kind: "in_process_session_exists",
+				message: `Project is already open in this backend runtime: ${storageTarget.canonicalProjectPath}`,
+				canonicalPathKey: storageTarget.canonicalPathKey,
+				holderSessionId
+			}, toSessionSnapshot(session, this.context.capabilities), {
+				sessionId: session.sessionId,
+				revision: session.revision
+			});
+		}
+		const diagnostics = validationDiagnostics(session.project);
+		if (diagnostics.length > 0) return failure("authoring", startedAt, {
+			code: "materialize_validation_failed",
+			message: `UAM materialize validation failed with ${diagnostics.length} issue(s).`,
+			sessionId: session.sessionId,
+			canonicalPathKey: session.canonicalPathKey,
+			issueCount: diagnostics.length,
+			diagnostics
+		}, toSessionSnapshot(session, this.context.capabilities), {
+			sessionId: session.sessionId,
+			revision: session.revision,
+			diagnostics
+		});
+		let document;
+		try {
+			document = (0, _openfairygui_core_uam.materializeUamProject)(session.project);
+		} catch (error) {
+			const diagnosticsFromError = [{
+				code: "materialize_validation_failed",
+				message: error instanceof Error ? error.message : String(error),
+				severity: "error",
+				operationKind: "materializeSession"
+			}];
+			return failure("authoring", startedAt, {
+				code: "materialize_validation_failed",
+				message: error instanceof Error ? error.message : String(error),
+				sessionId: session.sessionId,
+				canonicalPathKey: session.canonicalPathKey,
+				issueCount: diagnosticsFromError.length,
+				diagnostics: diagnosticsFromError
+			}, toSessionSnapshot(session, this.context.capabilities), {
+				sessionId: session.sessionId,
+				revision: session.revision,
+				diagnostics: diagnosticsFromError
+			});
+		}
+		const writtenPaths = [];
+		const failedPaths = [];
+		const skippedPaths = [];
+		this.eventService.emit({
+			kind: "save.started",
+			sessionId: session.sessionId,
+			canonicalPathKey: storageTarget?.canonicalPathKey ?? session.canonicalPathKey,
+			revision: session.revision
+		});
+		try {
+			await new _openfairygui_core_project_io.ProjectWriter(createWriterFileSystem(fileSystem, writtenPaths, failedPaths)).write(document, fairyPath);
+			if (storageTarget) {
+				this.context.sessionsByPath.delete(session.canonicalPathKey);
+				session.fileSystem = storageTarget.fileSystem;
+				session.fairyPath = storageTarget.fairyPath;
+				session.canonicalProjectPath = storageTarget.canonicalProjectPath;
+				session.canonicalPathKey = storageTarget.canonicalPathKey;
+				this.context.sessionsByPath.set(session.canonicalPathKey, session.sessionId);
+			}
+			session.lastSavedRevision = session.revision;
+			session.dirty = false;
+			const cacheEntry = this.cacheService.refreshSession(session);
+			this.eventService.emit({
+				kind: "save.completed",
+				sessionId: session.sessionId,
+				canonicalPathKey: session.canonicalPathKey,
+				revision: session.revision
+			});
+			this.eventService.emit({
+				kind: "cache.updated",
+				sessionId: session.sessionId,
+				canonicalPathKey: session.canonicalPathKey,
+				revision: session.revision,
+				cacheRevision: cacheEntry.revision
+			});
+			return success("authoring", startedAt, toMaterializeSnapshot(session, this.context.capabilities, {
+				reason: input.reason,
+				writtenPaths,
+				skippedPaths,
+				diagnostics: []
+			}), {
+				sessionId: session.sessionId,
+				revision: session.revision
+			});
+		} catch (error) {
+			const diagnosticsFromError = [{
+				code: "write_failed",
+				message: error instanceof Error ? error.message : String(error),
+				severity: "error",
+				path: failedPaths[0],
+				operationKind: "materializeSession"
+			}];
+			this.cacheService.invalidateSession(session);
+			this.eventService.emit({
+				kind: "save.failed",
+				sessionId: session.sessionId,
+				canonicalPathKey: session.canonicalPathKey,
+				revision: session.revision,
+				diagnostics: diagnosticsFromError
+			});
+			return failure("authoring", startedAt, {
+				code: "write_failed",
+				message: error instanceof Error ? error.message : String(error),
+				sessionId: session.sessionId,
+				canonicalPathKey: session.canonicalPathKey,
+				attemptedRevision: session.revision,
+				lastSavedRevision: session.lastSavedRevision,
+				writtenPaths,
+				failedPaths,
+				skippedPaths,
+				diagnostics: diagnosticsFromError,
+				diskMayBePartiallyUpdated: true
+			}, toSessionSnapshot(session, this.context.capabilities), {
+				sessionId: session.sessionId,
+				revision: session.revision,
+				diagnostics: diagnosticsFromError
+			});
+		}
+	}
 };
 //#endregion
 //#region src/services/cache-service.ts
@@ -909,6 +1098,7 @@ var RuntimeService = class {
 				canonicalProjectPath,
 				canonicalPathKey,
 				lockFilePath,
+				fileSystem,
 				project,
 				revision: 0,
 				lastSavedRevision: 0,
@@ -947,8 +1137,10 @@ var RuntimeService = class {
 	openProjectSession(input) {
 		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, {
 			code: "lock_conflict",
@@ -959,10 +1151,11 @@ var RuntimeService = class {
 		});
 		const session = {
 			sessionId,
-			fairyPath: canonicalProjectPath,
+			fairyPath: storage?.fairyPath ?? canonicalProjectPath,
 			canonicalProjectPath,
 			canonicalPathKey,
 			lockFilePath: "",
+			fileSystem: storage?.fileSystem,
 			project: (0, _openfairygui_core_uam.normalizeUamProject)(input.project),
 			revision: 0,
 			lastSavedRevision: 0,
@@ -1026,6 +1219,7 @@ const BACKEND_METHODS = [
 	"getSession",
 	"applyTransaction",
 	"saveSession",
+	"materializeSession",
 	"closeSession",
 	"getEvents",
 	"getJob",
@@ -1074,7 +1268,21 @@ function createCapabilities() {
 			adapters: {
 				fileSystem: {
 					injected: true,
-					requiredFor: ["openSession", "saveSession"]
+					requiredFor: [
+						"openSession",
+						"saveSession",
+						"materializeSession"
+					]
+				},
+				projectStorage: {
+					injected: true,
+					browserSafe: true,
+					requiredFor: [
+						"openProjectSession.writeback",
+						"saveSession",
+						"materializeSession"
+					],
+					adapterFactory: "createBackendStorageFileSystem"
 				},
 				host: {
 					injected: true,
@@ -1181,6 +1389,9 @@ var BackendRuntime = class {
 	async saveSession(input) {
 		return this.authoringService.saveSession(input);
 	}
+	async materializeSession(input) {
+		return this.authoringService.materializeSession(input);
+	}
 	async closeSession(input) {
 		return this.runtimeService.closeSession(input);
 	}