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

package/README.md

@@ -85,8 +85,15 @@ const opened = runtime.openProjectSession({
 });
 if (!opened.ok) throw new Error(opened.error.message);
 
-const saved = await runtime.saveSession({ sessionId: opened.data.sessionId });
-if (!saved.ok) throw new Error(saved.error.message);
+const bootstrapped = await runtime.materializeSession({
+	sessionId: opened.data.sessionId,
+	expectedRevision: opened.data.revision,
+	mode: 'fullProject',
+	reason: 'workspace_bootstrap',
+});
+if (!bootstrapped.ok) throw new Error(bootstrapped.error.message);
+
+console.log(bootstrapped.data.writtenPaths);
 ```
 
 Node file-backed session:

package/dist/index.cjs

@@ -1,5 +1,5 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_runtime = require("./runtime-YK3ACpuQ.cjs");
+const require_runtime = require("./runtime-GKzsXJdO.cjs");
 //#region src/storage.ts
 var StorageFileStat = class {
 	constructor(kind) {

package/dist/index.d.cts

@@ -1,4 +1,4 @@
-import { $ as BackendStage, A as BackendSessionSnapshot, B as ListJobsInput, C as BackendJobProgress, D as BackendResult, E as BackendProjectSessionStorage, F as GetCacheSnapshotInput, G as SessionNotFoundError, H as RefreshCacheInput, I as GetEventsInput, J as BACKEND_COMPATIBILITY_POLICY, K as SessionStaleWriteError, L as GetEventsSnapshot, M as CacheRefreshFailedError, N as CancelJobInput, O as BackendRuntime, P as EventCursorInvalidError, Q as BackendResponseMeta, R as GetJobInput, S as BackendJobNotFoundError, T as BackendJobStatus, U as SavePartialFailureError, V as OpenProjectSessionInput, W as SaveSessionInput, X as BackendDiagnostic, Y as BACKEND_CONTRACT_VERSION, Z as BackendMessage, _ as BackendJobErrors, a as BackendCacheSnapshot, b as BackendJobListStatusFilter, c as BackendCapabilityUnavailableError, d as BackendEventKind, f as BackendFailure, g as BackendHostAdapter, h as BackendFileSystem, i as BackendCacheEntry, j as BackendSuccess, k as BackendRuntimeOptions, l as BackendError, m as BackendFileStat, n as ApplySessionTransactionInput, o as BackendCapabilities, p as BackendFileHandle, q as BACKEND_CAPABILITY_SCHEMA_VERSION, r as BackendArtifactBridgeCapability, s as BackendCapabilityManifest, t as AdvisoryLockConflictError, u as BackendEvent, v as BackendJobKind, w as BackendJobSnapshot, x as BackendJobNotCancellableError, y as BackendJobListSnapshot, z as InProcessLockConflictError } from "./runtime-DziTGugy.cjs";
+import { $ as BACKEND_CONTRACT_VERSION, A as BackendSessionSnapshot, B as ListJobsInput, C as BackendJobProgress, D as BackendResult, E as BackendProjectSessionStorage, F as GetCacheSnapshotInput, G as OpenProjectSessionInput, H as MaterializeSessionSnapshot, I as GetEventsInput, J as SaveSessionInput, K as RefreshCacheInput, L as GetEventsSnapshot, M as CacheRefreshFailedError, N as CancelJobInput, O as BackendRuntime, P as EventCursorInvalidError, Q as BACKEND_COMPATIBILITY_POLICY, R as GetJobInput, S as BackendJobNotFoundError, T as BackendJobStatus, U as MaterializeValidationFailedError, V as MaterializeSessionInput, W as MaterializeWriteFailedError, X as SessionStaleWriteError, Y as SessionNotFoundError, Z as BACKEND_CAPABILITY_SCHEMA_VERSION, _ as BackendJobErrors, a as BackendCacheSnapshot, b as BackendJobListStatusFilter, c as BackendCapabilityUnavailableError, d as BackendEventKind, et as BackendDiagnostic, f as BackendFailure, g as BackendHostAdapter, h as BackendFileSystem, i as BackendCacheEntry, j as BackendSuccess, k as BackendRuntimeOptions, l as BackendError, m as BackendFileStat, n as ApplySessionTransactionInput, nt as BackendResponseMeta, o as BackendCapabilities, p as BackendFileHandle, q as SavePartialFailureError, r as BackendArtifactBridgeCapability, rt as BackendStage, s as BackendCapabilityManifest, t as AdvisoryLockConflictError, tt as BackendMessage, u as BackendEvent, v as BackendJobKind, w as BackendJobSnapshot, x as BackendJobNotCancellableError, y as BackendJobListSnapshot, z as InProcessLockConflictError } from "./runtime-Jec6FcF5.cjs";
 import { FileSystem } from "@openfairygui/core/project-io";
 
 //#region src/storage.d.ts
@@ -30,4 +30,4 @@ interface BackendAsyncStorageAdapter {
 type BackendStorageFileSystem = BackendFileSystem & FileSystem;
 declare function createBackendStorageFileSystem(storage: BackendAsyncStorageAdapter): BackendStorageFileSystem;
 //#endregion
-export { type AdvisoryLockConflictError, type ApplySessionTransactionInput, BACKEND_CAPABILITY_SCHEMA_VERSION, BACKEND_COMPATIBILITY_POLICY, BACKEND_CONTRACT_VERSION, type BackendArtifactBridgeCapability, type BackendAsyncStorageAdapter, type BackendCacheEntry, type BackendCacheSnapshot, type BackendCapabilities, type BackendCapabilityManifest, type BackendCapabilityUnavailableError, type BackendDiagnostic, type BackendError, type BackendEvent, type BackendEventKind, type BackendFailure, type BackendFileHandle, type BackendFileStat, type BackendFileSystem, type BackendHostAdapter, type BackendJobErrors, type BackendJobKind, type BackendJobListSnapshot, type BackendJobListStatusFilter, type BackendJobNotCancellableError, type BackendJobNotFoundError, type BackendJobProgress, type BackendJobSnapshot, type BackendJobStatus, type BackendMessage, type BackendProjectSessionStorage, type BackendResponseMeta, type BackendResult, BackendRuntime, type BackendRuntimeOptions, type BackendSessionSnapshot, type BackendStage, type BackendStorageFileSystem, type BackendStorageStatLike, type BackendSuccess, type CacheRefreshFailedError, type CancelJobInput, type EventCursorInvalidError, type GetCacheSnapshotInput, type GetEventsInput, type GetEventsSnapshot, type GetJobInput, type InProcessLockConflictError, type ListJobsInput, type OpenProjectSessionInput, type RefreshCacheInput, type SavePartialFailureError, type SaveSessionInput, type SessionNotFoundError, type SessionStaleWriteError, createBackendStorageFileSystem };
+export { type AdvisoryLockConflictError, type ApplySessionTransactionInput, BACKEND_CAPABILITY_SCHEMA_VERSION, BACKEND_COMPATIBILITY_POLICY, BACKEND_CONTRACT_VERSION, type BackendArtifactBridgeCapability, type BackendAsyncStorageAdapter, type BackendCacheEntry, type BackendCacheSnapshot, type BackendCapabilities, type BackendCapabilityManifest, type BackendCapabilityUnavailableError, type BackendDiagnostic, type BackendError, type BackendEvent, type BackendEventKind, type BackendFailure, type BackendFileHandle, type BackendFileStat, type BackendFileSystem, type BackendHostAdapter, type BackendJobErrors, type BackendJobKind, type BackendJobListSnapshot, type BackendJobListStatusFilter, type BackendJobNotCancellableError, type BackendJobNotFoundError, type BackendJobProgress, type BackendJobSnapshot, type BackendJobStatus, type BackendMessage, type BackendProjectSessionStorage, type BackendResponseMeta, type BackendResult, BackendRuntime, type BackendRuntimeOptions, type BackendSessionSnapshot, type BackendStage, type BackendStorageFileSystem, type BackendStorageStatLike, type BackendSuccess, type CacheRefreshFailedError, type CancelJobInput, type EventCursorInvalidError, type GetCacheSnapshotInput, type GetEventsInput, type GetEventsSnapshot, type GetJobInput, type InProcessLockConflictError, type ListJobsInput, type MaterializeSessionInput, type MaterializeSessionSnapshot, type MaterializeValidationFailedError, type MaterializeWriteFailedError, type OpenProjectSessionInput, type RefreshCacheInput, type SavePartialFailureError, type SaveSessionInput, type SessionNotFoundError, type SessionStaleWriteError, createBackendStorageFileSystem };

package/dist/index.d.mts

@@ -1,4 +1,4 @@
-import { $ as BackendStage, A as BackendSessionSnapshot, B as ListJobsInput, C as BackendJobProgress, D as BackendResult, E as BackendProjectSessionStorage, F as GetCacheSnapshotInput, G as SessionNotFoundError, H as RefreshCacheInput, I as GetEventsInput, J as BACKEND_COMPATIBILITY_POLICY, K as SessionStaleWriteError, L as GetEventsSnapshot, M as CacheRefreshFailedError, N as CancelJobInput, O as BackendRuntime, P as EventCursorInvalidError, Q as BackendResponseMeta, R as GetJobInput, S as BackendJobNotFoundError, T as BackendJobStatus, U as SavePartialFailureError, V as OpenProjectSessionInput, W as SaveSessionInput, X as BackendDiagnostic, Y as BACKEND_CONTRACT_VERSION, Z as BackendMessage, _ as BackendJobErrors, a as BackendCacheSnapshot, b as BackendJobListStatusFilter, c as BackendCapabilityUnavailableError, d as BackendEventKind, f as BackendFailure, g as BackendHostAdapter, h as BackendFileSystem, i as BackendCacheEntry, j as BackendSuccess, k as BackendRuntimeOptions, l as BackendError, m as BackendFileStat, n as ApplySessionTransactionInput, o as BackendCapabilities, p as BackendFileHandle, q as BACKEND_CAPABILITY_SCHEMA_VERSION, r as BackendArtifactBridgeCapability, s as BackendCapabilityManifest, t as AdvisoryLockConflictError, u as BackendEvent, v as BackendJobKind, w as BackendJobSnapshot, x as BackendJobNotCancellableError, y as BackendJobListSnapshot, z as InProcessLockConflictError } from "./runtime-Bydxr_SN.mjs";
+import { $ as BACKEND_CONTRACT_VERSION, A as BackendSessionSnapshot, B as ListJobsInput, C as BackendJobProgress, D as BackendResult, E as BackendProjectSessionStorage, F as GetCacheSnapshotInput, G as OpenProjectSessionInput, H as MaterializeSessionSnapshot, I as GetEventsInput, J as SaveSessionInput, K as RefreshCacheInput, L as GetEventsSnapshot, M as CacheRefreshFailedError, N as CancelJobInput, O as BackendRuntime, P as EventCursorInvalidError, Q as BACKEND_COMPATIBILITY_POLICY, R as GetJobInput, S as BackendJobNotFoundError, T as BackendJobStatus, U as MaterializeValidationFailedError, V as MaterializeSessionInput, W as MaterializeWriteFailedError, X as SessionStaleWriteError, Y as SessionNotFoundError, Z as BACKEND_CAPABILITY_SCHEMA_VERSION, _ as BackendJobErrors, a as BackendCacheSnapshot, b as BackendJobListStatusFilter, c as BackendCapabilityUnavailableError, d as BackendEventKind, et as BackendDiagnostic, f as BackendFailure, g as BackendHostAdapter, h as BackendFileSystem, i as BackendCacheEntry, j as BackendSuccess, k as BackendRuntimeOptions, l as BackendError, m as BackendFileStat, n as ApplySessionTransactionInput, nt as BackendResponseMeta, o as BackendCapabilities, p as BackendFileHandle, q as SavePartialFailureError, r as BackendArtifactBridgeCapability, rt as BackendStage, s as BackendCapabilityManifest, t as AdvisoryLockConflictError, tt as BackendMessage, u as BackendEvent, v as BackendJobKind, w as BackendJobSnapshot, x as BackendJobNotCancellableError, y as BackendJobListSnapshot, z as InProcessLockConflictError } from "./runtime-GyNVxAQ0.mjs";
 import { FileSystem } from "@openfairygui/core/project-io";
 
 //#region src/storage.d.ts
@@ -30,4 +30,4 @@ interface BackendAsyncStorageAdapter {
 type BackendStorageFileSystem = BackendFileSystem & FileSystem;
 declare function createBackendStorageFileSystem(storage: BackendAsyncStorageAdapter): BackendStorageFileSystem;
 //#endregion
-export { type AdvisoryLockConflictError, type ApplySessionTransactionInput, BACKEND_CAPABILITY_SCHEMA_VERSION, BACKEND_COMPATIBILITY_POLICY, BACKEND_CONTRACT_VERSION, type BackendArtifactBridgeCapability, type BackendAsyncStorageAdapter, type BackendCacheEntry, type BackendCacheSnapshot, type BackendCapabilities, type BackendCapabilityManifest, type BackendCapabilityUnavailableError, type BackendDiagnostic, type BackendError, type BackendEvent, type BackendEventKind, type BackendFailure, type BackendFileHandle, type BackendFileStat, type BackendFileSystem, type BackendHostAdapter, type BackendJobErrors, type BackendJobKind, type BackendJobListSnapshot, type BackendJobListStatusFilter, type BackendJobNotCancellableError, type BackendJobNotFoundError, type BackendJobProgress, type BackendJobSnapshot, type BackendJobStatus, type BackendMessage, type BackendProjectSessionStorage, type BackendResponseMeta, type BackendResult, BackendRuntime, type BackendRuntimeOptions, type BackendSessionSnapshot, type BackendStage, type BackendStorageFileSystem, type BackendStorageStatLike, type BackendSuccess, type CacheRefreshFailedError, type CancelJobInput, type EventCursorInvalidError, type GetCacheSnapshotInput, type GetEventsInput, type GetEventsSnapshot, type GetJobInput, type InProcessLockConflictError, type ListJobsInput, type OpenProjectSessionInput, type RefreshCacheInput, type SavePartialFailureError, type SaveSessionInput, type SessionNotFoundError, type SessionStaleWriteError, createBackendStorageFileSystem };
+export { type AdvisoryLockConflictError, type ApplySessionTransactionInput, BACKEND_CAPABILITY_SCHEMA_VERSION, BACKEND_COMPATIBILITY_POLICY, BACKEND_CONTRACT_VERSION, type BackendArtifactBridgeCapability, type BackendAsyncStorageAdapter, type BackendCacheEntry, type BackendCacheSnapshot, type BackendCapabilities, type BackendCapabilityManifest, type BackendCapabilityUnavailableError, type BackendDiagnostic, type BackendError, type BackendEvent, type BackendEventKind, type BackendFailure, type BackendFileHandle, type BackendFileStat, type BackendFileSystem, type BackendHostAdapter, type BackendJobErrors, type BackendJobKind, type BackendJobListSnapshot, type BackendJobListStatusFilter, type BackendJobNotCancellableError, type BackendJobNotFoundError, type BackendJobProgress, type BackendJobSnapshot, type BackendJobStatus, type BackendMessage, type BackendProjectSessionStorage, type BackendResponseMeta, type BackendResult, BackendRuntime, type BackendRuntimeOptions, type BackendSessionSnapshot, type BackendStage, type BackendStorageFileSystem, type BackendStorageStatLike, type BackendSuccess, type CacheRefreshFailedError, type CancelJobInput, type EventCursorInvalidError, type GetCacheSnapshotInput, type GetEventsInput, type GetEventsSnapshot, type GetJobInput, type InProcessLockConflictError, type ListJobsInput, type MaterializeSessionInput, type MaterializeSessionSnapshot, type MaterializeValidationFailedError, type MaterializeWriteFailedError, type OpenProjectSessionInput, type RefreshCacheInput, type SavePartialFailureError, type SaveSessionInput, type SessionNotFoundError, type SessionStaleWriteError, createBackendStorageFileSystem };

package/dist/index.mjs

@@ -1,4 +1,4 @@
-import { i as BACKEND_CONTRACT_VERSION, n as BACKEND_CAPABILITY_SCHEMA_VERSION, r as BACKEND_COMPATIBILITY_POLICY, t as BackendRuntime } from "./runtime-Cn0O-wZt.mjs";
+import { i as BACKEND_CONTRACT_VERSION, n as BACKEND_CAPABILITY_SCHEMA_VERSION, r as BACKEND_COMPATIBILITY_POLICY, t as BackendRuntime } from "./runtime-DFatY9W0.mjs";
 //#region src/storage.ts
 var StorageFileStat = class {
 	constructor(kind) {

package/dist/node.cjs

@@ -21,7 +21,7 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 	enumerable: true
 }) : target, mod));
 //#endregion
-const require_runtime = require("./runtime-YK3ACpuQ.cjs");
+const require_runtime = require("./runtime-GKzsXJdO.cjs");
 let node_fs_promises = require("node:fs/promises");
 node_fs_promises = __toESM(node_fs_promises);
 let node_path = require("node:path");

package/dist/node.d.cts

@@ -1,4 +1,4 @@
-import { O as BackendRuntime, g as BackendHostAdapter, h as BackendFileSystem, k as BackendRuntimeOptions, m as BackendFileStat, p as BackendFileHandle } from "./runtime-DziTGugy.cjs";
+import { O as BackendRuntime, g as BackendHostAdapter, h as BackendFileSystem, k as BackendRuntimeOptions, m as BackendFileStat, p as BackendFileHandle } from "./runtime-Jec6FcF5.cjs";
 
 //#region src/node.d.ts
 declare function createNodeBackendFileSystem(): BackendFileSystem;

package/dist/node.d.mts

@@ -1,4 +1,4 @@
-import { O as BackendRuntime, g as BackendHostAdapter, h as BackendFileSystem, k as BackendRuntimeOptions, m as BackendFileStat, p as BackendFileHandle } from "./runtime-Bydxr_SN.mjs";
+import { O as BackendRuntime, g as BackendHostAdapter, h as BackendFileSystem, k as BackendRuntimeOptions, m as BackendFileStat, p as BackendFileHandle } from "./runtime-GyNVxAQ0.mjs";
 
 //#region src/node.d.ts
 declare function createNodeBackendFileSystem(): BackendFileSystem;

package/dist/node.mjs

@@ -1,4 +1,4 @@
-import { t as BackendRuntime } from "./runtime-Cn0O-wZt.mjs";
+import { t as BackendRuntime } from "./runtime-DFatY9W0.mjs";
 import fs from "node:fs/promises";
 import path from "node:path";
 //#region src/node.ts

package/dist/{runtime-Cn0O-wZt.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,16 +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));
 		const fileSystem = input.fileSystem ?? session.fileSystem ?? this.context.fileSystem;
-		if (!fileSystem) return failure("authoring", startedAt, {
-			code: "capability_unavailable",
-			message: "saveSession requires an injected BackendFileSystem adapter.",
-			capability: "fileSystem",
-			requiredAdapter: "BackendFileSystem"
-		}, toSessionSnapshot(session, this.context.capabilities), {
+		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
 		});
@@ -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
@@ -1029,6 +1218,7 @@ const BACKEND_METHODS = [
 	"getSession",
 	"applyTransaction",
 	"saveSession",
+	"materializeSession",
 	"closeSession",
 	"getEvents",
 	"getJob",
@@ -1077,12 +1267,20 @@ function createCapabilities() {
 			adapters: {
 				fileSystem: {
 					injected: true,
-					requiredFor: ["openSession", "saveSession"]
+					requiredFor: [
+						"openSession",
+						"saveSession",
+						"materializeSession"
+					]
 				},
 				projectStorage: {
 					injected: true,
 					browserSafe: true,
-					requiredFor: ["openProjectSession.writeback", "saveSession"],
+					requiredFor: [
+						"openProjectSession.writeback",
+						"saveSession",
+						"materializeSession"
+					],
 					adapterFactory: "createBackendStorageFileSystem"
 				},
 				host: {
@@ -1190,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-YK3ACpuQ.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,16 +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));
 		const fileSystem = input.fileSystem ?? session.fileSystem ?? this.context.fileSystem;
-		if (!fileSystem) return failure("authoring", startedAt, {
-			code: "capability_unavailable",
-			message: "saveSession requires an injected BackendFileSystem adapter.",
-			capability: "fileSystem",
-			requiredAdapter: "BackendFileSystem"
-		}, toSessionSnapshot(session, this.context.capabilities), {
+		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
 		});
@@ -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
@@ -1030,6 +1219,7 @@ const BACKEND_METHODS = [
 	"getSession",
 	"applyTransaction",
 	"saveSession",
+	"materializeSession",
 	"closeSession",
 	"getEvents",
 	"getJob",
@@ -1078,12 +1268,20 @@ function createCapabilities() {
 			adapters: {
 				fileSystem: {
 					injected: true,
-					requiredFor: ["openSession", "saveSession"]
+					requiredFor: [
+						"openSession",
+						"saveSession",
+						"materializeSession"
+					]
 				},
 				projectStorage: {
 					injected: true,
 					browserSafe: true,
-					requiredFor: ["openProjectSession.writeback", "saveSession"],
+					requiredFor: [
+						"openProjectSession.writeback",
+						"saveSession",
+						"materializeSession"
+					],
 					adapterFactory: "createBackendStorageFileSystem"
 				},
 				host: {
@@ -1191,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);
 	}