@openfairygui/backend 0.2.0-alpha.2 → 0.2.0-alpha.21

package/dist/{runtime-BL9Pkfc7.cjs → runtime-D3bShb1X.cjs}

@@ -1,7 +1,7 @@
 require("./node.cjs");
 let _openfairygui_core_uam = require("@openfairygui/core/uam");
-let _openfairygui_core_project_io = require("@openfairygui/core/project-io");
 let _openfairygui_functions_uam = require("@openfairygui/functions/uam");
+let _openfairygui_core_project_io = require("@openfairygui/core/project-io");
 //#region src/contracts.ts
 const BACKEND_CONTRACT_VERSION = "1.1.0-p2";
 const BACKEND_CAPABILITY_SCHEMA_VERSION = 2;
@@ -76,24 +76,6 @@ async function validateSaveTarget(fileSystem, openedFairyPath, targetPath) {
 	};
 }
 //#endregion
-//#region src/services/artifact-service.ts
-function createArtifactCapabilities() {
-	const bridge = {
-		available: false,
-		requiredHost: "node",
-		executionBoundary: "external-bridge",
-		bridgeEntrypoint: "@openfairygui/backend/node",
-		reason: "publish/restore require explicit Node-hosted filesystem and artifact execution."
-	};
-	return {
-		publish: false,
-		restore: false,
-		status: "bridge-required",
-		publishBridge: bridge,
-		restoreBridge: bridge
-	};
-}
-//#endregion
 //#region src/services/context.ts
 function diagnosticFromError(error) {
 	return {
@@ -138,6 +120,48 @@ function failure(stage, startedAt, error, session, options) {
 	};
 }
 //#endregion
+//#region src/services/session-project-writer.ts
+function createWriterFileSystem(fileSystem, writtenPaths, failedPaths) {
+	async function trackWrite(targetPath, write) {
+		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) {
+			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))
+	};
+}
+async function writeSessionProject(input) {
+	await new _openfairygui_core_project_io.ProjectWriter(createWriterFileSystem(input.fileSystem, input.writtenPaths, input.failedPaths)).write(input.document, input.fairyPath, { staleSourceFiles: input.staleSourceFiles });
+}
+//#endregion
 //#region src/services/snapshot-utils.ts
 function cloneJsonValue(value) {
 	if (value === void 0 || value === null) return value;
@@ -180,6 +204,7 @@ function toSessionSnapshot(session, capabilities) {
 		revision: session.revision,
 		lastSavedRevision: session.lastSavedRevision,
 		dirty: session.dirty,
+		uamFidelity: session.uamFidelity,
 		lockHeld: session.lockHeld,
 		capabilities: cloneCapabilitiesSnapshot(capabilities)
 	};
@@ -203,65 +228,137 @@ function createStaleWriteError(session, expectedRevision) {
 }
 //#endregion
 //#region src/services/authoring-service.ts
-function createWriterFileSystem(fileSystem, committedPaths, failedPaths) {
-	async function trackWrite(targetPath, fn) {
-		try {
-			const result = await fn();
-			committedPaths.push(targetPath);
-			return result;
-		} catch (error) {
-			failedPaths.push(targetPath);
-			throw error;
+function projectSourceFiles(project) {
+	const result = /* @__PURE__ */ new Map();
+	for (const pkg of project.packages) {
+		result.set(`${pkg.id}/package.xml`, {
+			packageName: pkg.name,
+			branch: "",
+			path: "",
+			fileName: "package.xml"
+		});
+		const branches = /* @__PURE__ */ new Set();
+		for (const resource of pkg.resources) {
+			if (resource.branch) branches.add(resource.branch);
+			const fileName = resource.kind === "component" ? `${resource.name}.xml` : resource.fileName ?? resource.file ?? "";
+			if (!fileName) continue;
+			result.set(`${pkg.id}/${resource.id}`, {
+				packageName: pkg.name,
+				branch: resource.branch,
+				path: resource.path,
+				fileName
+			});
 		}
+		for (const branch of branches) result.set(`${pkg.id}/branch/${branch}`, {
+			packageName: pkg.name,
+			branch,
+			path: "",
+			fileName: "package_branch.xml"
+		});
 	}
+	return result;
+}
+function sourceFileKey(source) {
+	return [
+		source.branch,
+		source.packageName,
+		source.path,
+		source.fileName
+	].join("\0");
+}
+function recordStaleProjectFiles(session, previousProject, nextProject) {
+	if (!session.fileSystem) return;
+	const previousSources = projectSourceFiles(previousProject);
+	const nextSourceKeys = new Set([...projectSourceFiles(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) {
+	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
+	}];
+}
+function createCapabilityUnavailableError$1(message) {
 	return {
-		async readFile(filePath) {
-			return fileSystem.readFile(filePath);
-		},
-		async readFileRaw(filePath) {
-			return fileSystem.readFileRaw(filePath);
-		},
-		async writeFile(filePath, content) {
-			await trackWrite(filePath, async () => {
-				await fileSystem.mkdir(fileSystem.dirname(filePath), { recursive: true });
-				await fileSystem.writeFile(filePath, content);
-			});
-		},
-		async writeFileRaw(filePath, data) {
-			await trackWrite(filePath, async () => {
-				await fileSystem.mkdir(fileSystem.dirname(filePath), { recursive: true });
-				await fileSystem.writeFileRaw(filePath, data);
-			});
-		},
-		async mkdir(dirPath) {
-			await fileSystem.mkdir(dirPath, { recursive: true });
-		},
-		async readdir(dirPath) {
-			return fileSystem.readdir(dirPath);
-		},
-		async exists(filePath) {
-			try {
-				await fileSystem.stat(filePath);
-				return true;
-			} catch {
-				return false;
-			}
-		},
-		join(...paths) {
-			return fileSystem.join(...paths);
-		},
-		dirname(filePath) {
-			return fileSystem.dirname(filePath);
-		}
+		code: "capability_unavailable",
+		message,
+		capability: "fileSystem",
+		requiredAdapter: "BackendFileSystem"
+	};
+}
+function createUamFidelityUnsupportedError(session) {
+	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) {
+	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 {
+	sessionOperations = /* @__PURE__ */ new Map();
 	constructor(context, cacheService, eventService) {
 		this.context = context;
 		this.cacheService = cacheService;
 		this.eventService = eventService;
 	}
+	async runSessionExclusive(sessionId, operation) {
+		const previous = this.sessionOperations.get(sessionId) ?? Promise.resolve();
+		let release = () => void 0;
+		const current = new Promise((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);
+		}
+	}
 	async applyTransaction(input) {
+		return this.runSessionExclusive(input.sessionId, () => this.applyTransactionExclusive(input));
+	}
+	async applyTransactionExclusive(input) {
 		const startedAt = Date.now();
 		const session = this.context.sessions.get(input.sessionId);
 		if (!session || session.closed) return failure("authoring", startedAt, createSessionNotFoundError(input.sessionId));
@@ -282,22 +379,21 @@ var AuthoringService = class {
 			operations: input.operations
 		});
 		if (result.ok === false) {
+			const diagnostics = toBackendDiagnostics(result.error);
 			this.eventService.emit({
 				kind: "transaction.rejected",
 				sessionId: session.sessionId,
 				canonicalPathKey: session.canonicalPathKey,
 				revision: session.revision,
-				diagnostics: result.error.issues?.map((issue) => ({
-					code: result.error.code,
-					message: issue.message,
-					severity: "error"
-				})) ?? []
+				diagnostics
 			});
 			return failure("authoring", startedAt, result.error, toSessionSnapshot(session, this.context.capabilities), {
 				sessionId: session.sessionId,
-				revision: session.revision
+				revision: session.revision,
+				diagnostics
 			});
 		}
+		recordStaleProjectFiles(session, session.project, result.project);
 		session.project = result.project;
 		session.revision += 1;
 		session.dirty = true;
@@ -321,15 +417,22 @@ 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"
+		});
+		return this.runSessionExclusive(input.sessionId, () => this.saveSessionExclusive(input));
+	}
+	async saveSessionExclusive(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 (!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 = session.fileSystem ?? input.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
 		});
@@ -337,7 +440,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,
@@ -347,6 +449,10 @@ var AuthoringService = class {
 			sessionId: session.sessionId,
 			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 = [];
 		const failedPaths = [];
 		this.eventService.emit({
@@ -356,7 +462,17 @@ var AuthoringService = class {
 			revision: session.revision
 		});
 		try {
-			await new _openfairygui_core_project_io.ProjectWriter(createWriterFileSystem(fileSystem, committedPaths, failedPaths)).write((0, _openfairygui_core_uam.materializeUamProject)(session.project), session.fairyPath);
+			await writeSessionProject({
+				fileSystem,
+				document: (0, _openfairygui_core_uam.materializeUamProject)(session.project),
+				fairyPath: session.fairyPath,
+				staleSourceFiles: [...session.pendingStaleSourceFiles.values()],
+				writtenPaths: committedPaths,
+				failedPaths
+			});
+			session.fileSystem ??= fileSystem;
+			session.pendingStaleSourceFiles.clear();
+			(0, _openfairygui_core_uam.commitUamProjectSourcePaths)(session.project);
 			session.lastSavedRevision = session.revision;
 			session.dirty = false;
 			const cacheEntry = this.cacheService.refreshSession(session);
@@ -401,6 +517,172 @@ var AuthoringService = class {
 			});
 		}
 	}
+	async materializeSession(input) {
+		return this.runSessionExclusive(input.sessionId, () => this.materializeSessionExclusive(input));
+	}
+	async materializeSessionExclusive(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
+			});
+		}
+		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) 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 {
+			const isSessionStorageTarget = fileSystem === session.fileSystem && fairyPath === session.fairyPath;
+			await writeSessionProject({
+				fileSystem,
+				document,
+				fairyPath,
+				staleSourceFiles: isSessionStorageTarget ? [...session.pendingStaleSourceFiles.values()] : [],
+				writtenPaths,
+				failedPaths
+			});
+			if (isSessionStorageTarget) session.pendingStaleSourceFiles.clear();
+			if (storageTarget && !isSessionStorageTarget) session.pendingStaleSourceFiles.clear();
+			if (isSessionStorageTarget || storageTarget) (0, _openfairygui_core_uam.commitUamProjectSourcePaths)(session.project);
+			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
@@ -859,6 +1141,68 @@ function createProjectReaderFileSystem(fileSystem) {
 		}
 	};
 }
+function createCaptureFileSystem(files) {
+	const normalize = (filePath) => filePath.replace(/\\/g, "/").replace(/\/+/g, "/");
+	return {
+		async readFile(filePath) {
+			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) {
+			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, content) {
+			files.set(normalize(filePath), content);
+		},
+		async writeFileRaw(filePath, data) {
+			files.set(normalize(filePath), data.slice());
+		},
+		async mkdir() {},
+		async readdir() {
+			return [];
+		},
+		async exists(filePath) {
+			return files.has(normalize(filePath));
+		},
+		join(...paths) {
+			return normalize(paths.filter(Boolean).join("/"));
+		},
+		dirname(filePath) {
+			const normalized = normalize(filePath);
+			const separator = normalized.lastIndexOf("/");
+			return separator < 0 ? "" : normalized.slice(0, separator);
+		},
+		async unlink(filePath) {
+			files.delete(normalize(filePath));
+		}
+	};
+}
+function capturedFilesEqual(left, right) {
+	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, project) {
+	const sourceFiles = /* @__PURE__ */ new Map();
+	const materializedFiles = /* @__PURE__ */ new Map();
+	try {
+		await Promise.all([new _openfairygui_core_project_io.ProjectWriter(createCaptureFileSystem(sourceFiles)).write(document, "Project.fairy"), new _openfairygui_core_project_io.ProjectWriter(createCaptureFileSystem(materializedFiles)).write((0, _openfairygui_core_uam.materializeUamProject)(project), "Project.fairy")]);
+	} catch {
+		return false;
+	}
+	return capturedFilesEqual(sourceFiles, materializedFiles);
+}
 var RuntimeService = class {
 	constructor(context, cacheService, eventService, jobService) {
 		this.context = context;
@@ -893,7 +1237,8 @@ var RuntimeService = class {
 				canonicalPathKey
 			}));
 			await advisoryLock.close();
-			const project = (0, _openfairygui_core_uam.liftDocumentToUamProject)(await new _openfairygui_core_project_io.ProjectReader(createProjectReaderFileSystem(fileSystem)).read(fairyPath));
+			const document = await new _openfairygui_core_project_io.ProjectReader(createProjectReaderFileSystem(fileSystem)).read(fairyPath, { hydrateResourceBytes: true });
+			const project = (0, _openfairygui_core_uam.liftDocumentToUamProject)(document);
 			const sessionId = randomId();
 			const session = {
 				sessionId,
@@ -901,9 +1246,12 @@ var RuntimeService = class {
 				canonicalProjectPath,
 				canonicalPathKey,
 				lockFilePath,
+				fileSystem,
 				project,
+				uamFidelity: await hasFullUamFidelity(document, project) ? "full" : "unsupported",
 				revision: 0,
 				lastSavedRevision: 0,
+				pendingStaleSourceFiles: /* @__PURE__ */ new Map(),
 				dirty: false,
 				lockHeld: true,
 				closed: false
@@ -939,8 +1287,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",
@@ -951,13 +1301,16 @@ 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),
+			uamFidelity: "full",
 			revision: 0,
 			lastSavedRevision: 0,
+			pendingStaleSourceFiles: /* @__PURE__ */ new Map(),
 			dirty: false,
 			lockHeld: false,
 			closed: false
@@ -1010,7 +1363,25 @@ var RuntimeService = class {
 	}
 };
 //#endregion
-//#region src/runtime.ts
+//#region src/services/artifact-service.ts
+function createArtifactCapabilities() {
+	const bridge = {
+		available: false,
+		requiredHost: "node",
+		executionBoundary: "external-bridge",
+		bridgeEntrypoint: "@openfairygui/backend/node",
+		reason: "publish/restore require explicit Node-hosted filesystem and artifact execution."
+	};
+	return {
+		publish: false,
+		restore: false,
+		status: "bridge-required",
+		publishBridge: bridge,
+		restoreBridge: bridge
+	};
+}
+//#endregion
+//#region src/runtime/capabilities.ts
 const BACKEND_METHODS = [
 	"getCapabilities",
 	"openSession",
@@ -1018,6 +1389,7 @@ const BACKEND_METHODS = [
 	"getSession",
 	"applyTransaction",
 	"saveSession",
+	"materializeSession",
 	"closeSession",
 	"getEvents",
 	"getJob",
@@ -1051,6 +1423,11 @@ function createCapabilities() {
 			resourceKinds: [..._openfairygui_core_uam.UAM_SUPPORTED_MATERIALIZATION_SCOPE.resourceKinds],
 			nodeKinds: [..._openfairygui_core_uam.UAM_SUPPORTED_MATERIALIZATION_SCOPE.nodeKinds],
 			gearKinds: [..._openfairygui_core_uam.UAM_SUPPORTED_MATERIALIZATION_SCOPE.gearKinds],
+			transactionScope: {
+				resourceKinds: [..._openfairygui_core_uam.UAM_SUPPORTED_TRANSACTION_SCOPE.resourceKinds],
+				nodeKinds: [..._openfairygui_core_uam.UAM_SUPPORTED_TRANSACTION_SCOPE.nodeKinds],
+				gearKinds: [..._openfairygui_core_uam.UAM_SUPPORTED_TRANSACTION_SCOPE.gearKinds]
+			},
 			unsupported: ["artifact.publish", "artifact.restore"]
 		},
 		artifact: createArtifactCapabilities(),
@@ -1061,7 +1438,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,
@@ -1110,6 +1501,8 @@ function createCapabilities() {
 		}
 	};
 }
+//#endregion
+//#region src/runtime.ts
 var BackendRuntime = class {
 	fileSystem;
 	capabilities;
@@ -1168,6 +1561,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);
 	}