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

package/dist/{runtime-jKuQmcqM.cjs → runtime-DtcaaVfy.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,38 +120,50 @@ function failure(stage, startedAt, error, session, options) {
 	};
 }
 //#endregion
-//#region src/services/snapshot-utils.ts
-function cloneJsonValue(value) {
-	if (value === void 0 || value === null) return value;
-	return JSON.parse(JSON.stringify(value));
-}
-function cloneEventSnapshot(event) {
-	return {
-		...event,
-		diagnostics: event.diagnostics.map((diagnostic) => ({ ...diagnostic })),
-		payload: cloneJsonValue(event.payload)
-	};
-}
-function cloneJobSnapshot(job) {
-	return {
-		...job,
-		diagnostics: job.diagnostics.map((diagnostic) => ({ ...diagnostic })),
-		progress: job.progress ? { ...job.progress } : void 0,
-		result: cloneJsonValue(job.result),
-		error: cloneJsonValue(job.error)
-	};
-}
-function cloneCacheEntrySnapshot(entry) {
-	return {
-		...entry,
-		summary: {
-			...entry.summary,
-			diagnostics: entry.summary.diagnostics.map((diagnostic) => ({ ...diagnostic }))
+//#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)),
+		rmdir: (path) => trackWrite(path, () => fileSystem.rmdir(path))
 	};
 }
-function cloneCapabilitiesSnapshot(capabilities) {
-	return cloneJsonValue(capabilities);
+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,
+		staleResourceFolders: input.staleResourceFolders
+	});
 }
 //#endregion
 //#region src/services/session-utils.ts
@@ -180,8 +174,9 @@ function toSessionSnapshot(session, capabilities) {
 		revision: session.revision,
 		lastSavedRevision: session.lastSavedRevision,
 		dirty: session.dirty,
+		uamFidelity: session.uamFidelity,
 		lockHeld: session.lockHeld,
-		capabilities: cloneCapabilitiesSnapshot(capabilities)
+		capabilities: structuredClone(capabilities)
 	};
 }
 function createSessionNotFoundError(sessionId) {
@@ -203,65 +198,111 @@ 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 sourceFileKey(source) {
+	return [
+		source.branch,
+		source.packageName,
+		source.path,
+		source.fileName
+	].join("\0");
+}
+function resourceFolderKey(folder) {
+	return [
+		folder.branch,
+		folder.packageName,
+		folder.path
+	].join("\0");
+}
+function recordStaleProjectFiles(session, previousProject, nextProject) {
+	if (!session.fileSystem) return;
+	for (const source of (0, _openfairygui_core_uam.staleSourceFiles)(previousProject, nextProject)) session.pendingStaleSourceFiles.set(sourceFileKey(source), source);
+	for (const source of (0, _openfairygui_core_uam.staleSourceFiles)(nextProject, previousProject)) session.pendingStaleSourceFiles.delete(sourceFileKey(source));
+	for (const folder of (0, _openfairygui_core_uam.staleResourceFolders)(previousProject, nextProject)) session.pendingStaleResourceFolders.set(resourceFolderKey(folder), folder);
+	for (const folder of (0, _openfairygui_core_uam.staleResourceFolders)(nextProject, previousProject)) session.pendingStaleResourceFolders.delete(resourceFolderKey(folder));
+}
+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 +323,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 +361,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 +384,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 +393,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 +406,19 @@ 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()],
+				staleResourceFolders: [...session.pendingStaleResourceFolders.values()],
+				writtenPaths: committedPaths,
+				failedPaths
+			});
+			session.fileSystem ??= fileSystem;
+			session.pendingStaleSourceFiles.clear();
+			session.pendingStaleResourceFolders.clear();
+			(0, _openfairygui_core_uam.commitUamProjectSourcePaths)(session.project);
 			session.lastSavedRevision = session.revision;
 			session.dirty = false;
 			const cacheEntry = this.cacheService.refreshSession(session);
@@ -401,6 +463,179 @@ 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()] : [],
+				staleResourceFolders: isSessionStorageTarget ? [...session.pendingStaleResourceFolders.values()] : [],
+				writtenPaths,
+				failedPaths
+			});
+			if (isSessionStorageTarget) {
+				session.pendingStaleSourceFiles.clear();
+				session.pendingStaleResourceFolders.clear();
+			}
+			if (storageTarget && !isSessionStorageTarget) {
+				session.pendingStaleSourceFiles.clear();
+				session.pendingStaleResourceFolders.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
@@ -431,7 +666,7 @@ var CacheService = class {
 		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
@@ -502,7 +737,7 @@ var EventService = class {
 		const filtered = events.filter((event) => event.sequence > after);
 		const limit = input.limit === void 0 ? 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
@@ -577,7 +812,7 @@ var JobService = class {
 			jobId
 		});
 		this.scheduleRefreshJob(session.sessionId, jobId);
-		return success("runtime", startedAt, cloneJobSnapshot(job), {
+		return success("runtime", startedAt, structuredClone(job), {
 			sessionId: session.sessionId,
 			revision: session.revision
 		});
@@ -596,7 +831,7 @@ var JobService = class {
 			sessionId: session.sessionId,
 			revision: session.revision
 		});
-		return success("runtime", startedAt, cloneJobSnapshot(job), {
+		return success("runtime", startedAt, structuredClone(job), {
 			sessionId: session.sessionId,
 			revision: session.revision
 		});
@@ -611,7 +846,7 @@ var JobService = class {
 		else if (input.status === "terminal") jobs = jobs.filter((job) => isTerminal(job.status));
 		else jobs = jobs.filter((job) => job.status === input.status);
 		if (input.limit !== void 0) jobs = jobs.slice(0, Math.max(0, input.limit));
-		return success("runtime", startedAt, { jobs: jobs.map(cloneJobSnapshot) }, {
+		return success("runtime", startedAt, { jobs: jobs.map((job) => structuredClone(job)) }, {
 			sessionId: session.sessionId,
 			revision: session.revision
 		});
@@ -648,7 +883,8 @@ var JobService = class {
 			revision: session.revision,
 			jobId: job.jobId
 		});
-		return success("runtime", startedAt, cloneJobSnapshot(this.cancelRefreshJob(session.sessionId, job)), {
+		const cancelled = this.cancelRefreshJob(session.sessionId, job);
+		return success("runtime", startedAt, structuredClone(cancelled), {
 			sessionId: session.sessionId,
 			revision: session.revision
 		});
@@ -795,7 +1031,7 @@ var ReadService = class {
 		this.context = context;
 	}
 	getCapabilities() {
-		return success("read", Date.now(), cloneCapabilitiesSnapshot(this.context.capabilities));
+		return success("read", Date.now(), structuredClone(this.context.capabilities));
 	}
 	getSession(input) {
 		const startedAt = Date.now();
@@ -859,6 +1095,75 @@ function createProjectReaderFileSystem(fileSystem) {
 		}
 	};
 }
+function createCaptureFileSystem(files, directories) {
+	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(dirPath) {
+			directories.add(normalize(dirPath));
+		},
+		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;
+}
+function capturedDirectoriesEqual(left, right) {
+	return left.size === right.size && [...left].every((directory) => right.has(directory));
+}
+async function hasFullUamFidelity(document, project) {
+	const sourceFiles = /* @__PURE__ */ new Map();
+	const materializedFiles = /* @__PURE__ */ new Map();
+	const sourceDirectories = /* @__PURE__ */ new Set();
+	const materializedDirectories = /* @__PURE__ */ new Set();
+	try {
+		await Promise.all([new _openfairygui_core_project_io.ProjectWriter(createCaptureFileSystem(sourceFiles, sourceDirectories)).write(document, "Project.fairy"), new _openfairygui_core_project_io.ProjectWriter(createCaptureFileSystem(materializedFiles, materializedDirectories)).write((0, _openfairygui_core_uam.materializeUamProject)(project), "Project.fairy")]);
+	} catch {
+		return false;
+	}
+	return capturedFilesEqual(sourceFiles, materializedFiles) && capturedDirectoriesEqual(sourceDirectories, materializedDirectories);
+}
 var RuntimeService = class {
 	constructor(context, cacheService, eventService, jobService) {
 		this.context = context;
@@ -893,7 +1198,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 +1207,13 @@ var RuntimeService = class {
 				canonicalProjectPath,
 				canonicalPathKey,
 				lockFilePath,
+				fileSystem,
 				project,
+				uamFidelity: await hasFullUamFidelity(document, project) ? "full" : "unsupported",
 				revision: 0,
 				lastSavedRevision: 0,
+				pendingStaleSourceFiles: /* @__PURE__ */ new Map(),
+				pendingStaleResourceFolders: /* @__PURE__ */ new Map(),
 				dirty: false,
 				lockHeld: true,
 				closed: false
@@ -939,8 +1249,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 +1263,17 @@ 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(),
+			pendingStaleResourceFolders: /* @__PURE__ */ new Map(),
 			dirty: false,
 			lockHeld: false,
 			closed: false
@@ -1010,7 +1326,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 +1352,7 @@ const BACKEND_METHODS = [
 	"getSession",
 	"applyTransaction",
 	"saveSession",
+	"materializeSession",
 	"closeSession",
 	"getEvents",
 	"getJob",
@@ -1066,7 +1401,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,
@@ -1115,6 +1464,8 @@ function createCapabilities() {
 		}
 	};
 }
+//#endregion
+//#region src/runtime.ts
 var BackendRuntime = class {
 	fileSystem;
 	capabilities;
@@ -1173,6 +1524,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);
 	}