@openfairygui/backend 0.2.0-alpha.1 → 0.2.0-alpha.13

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

@@ -1,6 +1,7 @@
 require("./node.cjs");
-let _openfairygui_core = require("@openfairygui/core");
-let _openfairygui_functions = require("@openfairygui/functions");
+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");
 //#region src/contracts.ts
 const BACKEND_CONTRACT_VERSION = "1.1.0-p2";
 const BACKEND_CAPABILITY_SCHEMA_VERSION = 2;
@@ -254,6 +255,54 @@ function createWriterFileSystem(fileSystem, committedPaths, failedPaths) {
 		}
 	};
 }
+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 {
+		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;
@@ -276,25 +325,23 @@ var AuthoringService = class {
 				revision: session.revision
 			});
 		}
-		const result = (0, _openfairygui_functions.applyUamTransactionApp)({
+		const result = (0, _openfairygui_functions_uam.applyUamTransactionApp)({
 			project: session.project,
 			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
 			});
 		}
 		session.project = result.project;
@@ -320,15 +367,19 @@ var AuthoringService = class {
 		});
 	}
 	async saveSession(input) {
+		if (input.force === true || input.mode === "materializeCleanSession") return this.materializeSession({
+			sessionId: input.sessionId,
+			expectedRevision: input.expectedRevision,
+			targetPath: input.targetPath,
+			fileSystem: input.fileSystem,
+			mode: "fullProject",
+			reason: "force_save"
+		});
 		const startedAt = Date.now();
 		const session = this.context.sessions.get(input.sessionId);
 		if (!session || session.closed) return failure("authoring", startedAt, createSessionNotFoundError(input.sessionId));
-		if (!this.context.fileSystem) return failure("authoring", startedAt, {
-			code: "capability_unavailable",
-			message: "saveSession requires an injected BackendFileSystem adapter.",
-			capability: "fileSystem",
-			requiredAdapter: "BackendFileSystem"
-		}, toSessionSnapshot(session, this.context.capabilities), {
+		const fileSystem = input.fileSystem ?? session.fileSystem ?? this.context.fileSystem;
+		if (!fileSystem) return failure("authoring", startedAt, createCapabilityUnavailableError$1("saveSession requires an injected BackendFileSystem adapter."), toSessionSnapshot(session, this.context.capabilities), {
 			sessionId: session.sessionId,
 			revision: session.revision
 		});
@@ -336,7 +387,6 @@ var AuthoringService = class {
 			sessionId: session.sessionId,
 			revision: session.revision
 		});
-		const fileSystem = this.context.fileSystem;
 		const targetViolation = await validateSaveTarget(fileSystem, session.fairyPath, input.targetPath);
 		if (targetViolation) return failure("authoring", startedAt, targetViolation, toSessionSnapshot(session, this.context.capabilities), {
 			sessionId: session.sessionId,
@@ -355,7 +405,7 @@ var AuthoringService = class {
 			revision: session.revision
 		});
 		try {
-			await new _openfairygui_core.ProjectWriter(createWriterFileSystem(fileSystem, committedPaths, failedPaths)).write((0, _openfairygui_core.materializeUamProject)(session.project), session.fairyPath);
+			await new _openfairygui_core_project_io.ProjectWriter(createWriterFileSystem(fileSystem, committedPaths, failedPaths)).write((0, _openfairygui_core_uam.materializeUamProject)(session.project), session.fairyPath);
 			session.lastSavedRevision = session.revision;
 			session.dirty = false;
 			const cacheEntry = this.cacheService.refreshSession(session);
@@ -400,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
@@ -892,7 +1090,7 @@ var RuntimeService = class {
 				canonicalPathKey
 			}));
 			await advisoryLock.close();
-			const project = (0, _openfairygui_core.liftDocumentToUamProject)(await new _openfairygui_core.ProjectReader(createProjectReaderFileSystem(fileSystem)).read(fairyPath));
+			const project = (0, _openfairygui_core_uam.liftDocumentToUamProject)(await new _openfairygui_core_project_io.ProjectReader(createProjectReaderFileSystem(fileSystem)).read(fairyPath));
 			const sessionId = randomId();
 			const session = {
 				sessionId,
@@ -900,6 +1098,7 @@ var RuntimeService = class {
 				canonicalProjectPath,
 				canonicalPathKey,
 				lockFilePath,
+				fileSystem,
 				project,
 				revision: 0,
 				lastSavedRevision: 0,
@@ -938,8 +1137,10 @@ var RuntimeService = class {
 	openProjectSession(input) {
 		const startedAt = Date.now();
 		const sessionId = input.sessionId ?? randomId();
-		const canonicalProjectPath = input.canonicalProjectPath ?? `memory://${sessionId}`;
-		const canonicalPathKey = input.canonicalPathKey ?? canonicalProjectPath.toLowerCase();
+		const storage = input.storage;
+		const memoryProjectPath = `memory://${sessionId}`;
+		const canonicalProjectPath = storage?.canonicalProjectPath ?? input.canonicalProjectPath ?? (storage ? storage.fileSystem.dirname(storage.fairyPath) || "." : memoryProjectPath);
+		const canonicalPathKey = storage?.canonicalPathKey ?? input.canonicalPathKey ?? (storage ? normalizeComparablePath(canonicalProjectPath) : canonicalProjectPath.toLowerCase());
 		const existingSessionId = this.context.sessionsByPath.get(canonicalPathKey);
 		if (existingSessionId) return failure("runtime", startedAt, {
 			code: "lock_conflict",
@@ -950,11 +1151,12 @@ var RuntimeService = class {
 		});
 		const session = {
 			sessionId,
-			fairyPath: canonicalProjectPath,
+			fairyPath: storage?.fairyPath ?? canonicalProjectPath,
 			canonicalProjectPath,
 			canonicalPathKey,
 			lockFilePath: "",
-			project: (0, _openfairygui_core.normalizeUamProject)(input.project),
+			fileSystem: storage?.fileSystem,
+			project: (0, _openfairygui_core_uam.normalizeUamProject)(input.project),
 			revision: 0,
 			lastSavedRevision: 0,
 			dirty: false,
@@ -1017,6 +1219,7 @@ const BACKEND_METHODS = [
 	"getSession",
 	"applyTransaction",
 	"saveSession",
+	"materializeSession",
 	"closeSession",
 	"getEvents",
 	"getJob",
@@ -1047,9 +1250,14 @@ function createCapabilities() {
 		authoring: {
 			applyTransaction: true,
 			saveSession: true,
-			resourceKinds: [..._openfairygui_core.UAM_SUPPORTED_MATERIALIZATION_SCOPE.resourceKinds],
-			nodeKinds: [..._openfairygui_core.UAM_SUPPORTED_MATERIALIZATION_SCOPE.nodeKinds],
-			gearKinds: [..._openfairygui_core.UAM_SUPPORTED_MATERIALIZATION_SCOPE.gearKinds],
+			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(),
@@ -1060,7 +1268,21 @@ function createCapabilities() {
 			adapters: {
 				fileSystem: {
 					injected: true,
-					requiredFor: ["openSession", "saveSession"]
+					requiredFor: [
+						"openSession",
+						"saveSession",
+						"materializeSession"
+					]
+				},
+				projectStorage: {
+					injected: true,
+					browserSafe: true,
+					requiredFor: [
+						"openProjectSession.writeback",
+						"saveSession",
+						"materializeSession"
+					],
+					adapterFactory: "createBackendStorageFileSystem"
 				},
 				host: {
 					injected: true,
@@ -1167,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);
 	}

package/dist/{runtime-C5JY_kRI.d.cts → runtime-GyNVxAQ0.d.mts}

@@ -1,5 +1,5 @@
-import { UamProject, UamTransactionOperation } from "@openfairygui/core";
-import { ApplyUamTransactionAppError } from "@openfairygui/functions";
+import { UamProject, UamTransactionOperation } from "@openfairygui/core/uam";
+import { ApplyUamTransactionAppError } from "@openfairygui/functions/uam";
 
 //#region src/contracts.d.ts
 declare const BACKEND_CONTRACT_VERSION: "1.1.0-p2";
@@ -18,6 +18,14 @@ interface BackendDiagnostic {
   code: string;
   message: string;
   severity: 'info' | 'warning' | 'error';
+  path?: string;
+  nodeKind?: string;
+  resourceKind?: string;
+  gearKind?: string;
+  field?: string;
+  operationKind?: string;
+  opIndex?: number;
+  opId?: string;
 }
 interface BackendResponseMeta {
   requestId: string;
@@ -87,7 +95,13 @@ interface BackendCapabilityManifest {
   adapters: {
     fileSystem: {
       injected: true;
-      requiredFor: readonly ['openSession', 'saveSession'];
+      requiredFor: readonly ['openSession', 'saveSession', 'materializeSession'];
+    };
+    projectStorage: {
+      injected: true;
+      browserSafe: true;
+      requiredFor: readonly ['openProjectSession.writeback', 'saveSession', 'materializeSession'];
+      adapterFactory: 'createBackendStorageFileSystem';
     };
     host: {
       injected: true;
@@ -111,7 +125,7 @@ interface BackendCapabilities {
   transactionKernelOwner: '@openfairygui/core';
   appSeamOwner: '@openfairygui/functions';
   runtimeOwner: '@openfairygui/backend';
-  methods: readonly ['getCapabilities', 'openSession', 'openProjectSession', 'getSession', 'applyTransaction', 'saveSession', 'closeSession', 'getEvents', 'getJob', 'listJobs', 'cancelJob', 'getCacheSnapshot', 'refreshCache'];
+  methods: readonly ['getCapabilities', 'openSession', 'openProjectSession', 'getSession', 'applyTransaction', 'saveSession', 'materializeSession', 'closeSession', 'getEvents', 'getJob', 'listJobs', 'cancelJob', 'getCacheSnapshot', 'refreshCache'];
   read: {
     capabilitySnapshot: true;
     sessionSnapshot: true;
@@ -122,6 +136,11 @@ interface BackendCapabilities {
     resourceKinds: readonly string[];
     nodeKinds: readonly string[];
     gearKinds: readonly string[];
+    transactionScope: {
+      resourceKinds: readonly string[];
+      nodeKinds: readonly string[];
+      gearKinds: readonly string[];
+    };
     unsupported: readonly ['artifact.publish', 'artifact.restore'];
   };
   artifact: {
@@ -177,6 +196,15 @@ interface BackendSessionSnapshot {
   lockHeld: boolean;
   capabilities: BackendCapabilities;
 }
+interface MaterializeSessionSnapshot extends BackendSessionSnapshot {
+  mode: 'fullProject';
+  reason?: string;
+  materializeRevision: number;
+  saveRevision: number;
+  writtenPaths: string[];
+  skippedPaths: string[];
+  diagnostics: BackendDiagnostic[];
+}
 interface BackendSuccess<T> {
   ok: true;
   meta: BackendResponseMeta;
@@ -229,6 +257,27 @@ interface SavePartialFailureError {
   failedPaths: string[];
   diskMayBePartiallyUpdated: true;
 }
+interface MaterializeValidationFailedError {
+  code: 'materialize_validation_failed';
+  message: string;
+  sessionId: string;
+  canonicalPathKey: string;
+  issueCount: number;
+  diagnostics: BackendDiagnostic[];
+}
+interface MaterializeWriteFailedError {
+  code: 'write_failed';
+  message: string;
+  sessionId: string;
+  canonicalPathKey: string;
+  attemptedRevision: number;
+  lastSavedRevision: number;
+  writtenPaths: string[];
+  failedPaths: string[];
+  skippedPaths: string[];
+  diagnostics: BackendDiagnostic[];
+  diskMayBePartiallyUpdated: true;
+}
 type BackendEventKind = 'session.opened' | 'transaction.applied' | 'transaction.rejected' | 'save.started' | 'save.completed' | 'save.failed' | 'session.closeRequested' | 'session.closed' | 'cache.invalidated' | 'cache.updated' | 'job.created' | 'job.started' | 'job.progress' | 'job.cancelRequested' | 'job.cancelled' | 'job.completed' | 'job.failed';
 interface BackendEvent {
   sequence: number;
@@ -360,7 +409,7 @@ interface RefreshCacheInput {
   sessionId: string;
   reason?: 'manual' | 'session_open' | 'after_save';
 }
-type BackendError = SessionNotFoundError | SessionStaleWriteError | InProcessLockConflictError | AdvisoryLockConflictError | SavePartialFailureError | PathPolicyViolationError | EventCursorInvalidError | BackendJobNotFoundError | BackendJobNotCancellableError | BackendJobCancelledError | CacheRefreshFailedError | BackendCapabilityUnavailableError | ApplyUamTransactionAppError;
+type BackendError = SessionNotFoundError | SessionStaleWriteError | InProcessLockConflictError | AdvisoryLockConflictError | SavePartialFailureError | MaterializeValidationFailedError | MaterializeWriteFailedError | PathPolicyViolationError | EventCursorInvalidError | BackendJobNotFoundError | BackendJobNotCancellableError | BackendJobCancelledError | CacheRefreshFailedError | BackendCapabilityUnavailableError | ApplyUamTransactionAppError;
 interface ApplySessionTransactionInput {
   sessionId: string;
   expectedRevision: number;
@@ -371,6 +420,30 @@ interface OpenProjectSessionInput {
   sessionId?: string;
   canonicalProjectPath?: string;
   canonicalPathKey?: string;
+  storage?: BackendProjectSessionStorage;
+}
+interface BackendProjectSessionStorage {
+  fileSystem: BackendFileSystem;
+  fairyPath: string;
+  canonicalProjectPath?: string;
+  canonicalPathKey?: string;
+}
+interface SaveSessionInput {
+  sessionId: string;
+  expectedRevision?: number;
+  targetPath?: string;
+  fileSystem?: BackendFileSystem;
+  force?: boolean;
+  mode?: 'materializeCleanSession';
+}
+interface MaterializeSessionInput {
+  sessionId: string;
+  expectedRevision?: number;
+  storage?: BackendProjectSessionStorage;
+  targetPath?: string;
+  fileSystem?: BackendFileSystem;
+  mode?: 'fullProject';
+  reason?: string;
 }
 interface BackendRuntimeOptions {
   fileSystem?: BackendFileSystem;
@@ -402,11 +475,8 @@ declare class BackendRuntime {
     sessionId: string;
   }): BackendResult<BackendSessionSnapshot, SessionNotFoundError>;
   applyTransaction(input: ApplySessionTransactionInput): Promise<BackendResult<BackendSessionSnapshot, SessionNotFoundError | SessionStaleWriteError | ApplyUamTransactionAppError>>;
-  saveSession(input: {
-    sessionId: string;
-    expectedRevision?: number;
-    targetPath?: string;
-  }): Promise<BackendResult<BackendSessionSnapshot, SessionNotFoundError | SessionStaleWriteError | SavePartialFailureError | PathPolicyViolationError | BackendCapabilityUnavailableError>>;
+  saveSession(input: SaveSessionInput): Promise<BackendResult<BackendSessionSnapshot | MaterializeSessionSnapshot, SessionNotFoundError | SessionStaleWriteError | SavePartialFailureError | MaterializeValidationFailedError | MaterializeWriteFailedError | PathPolicyViolationError | InProcessLockConflictError | BackendCapabilityUnavailableError>>;
+  materializeSession(input: MaterializeSessionInput): Promise<BackendResult<MaterializeSessionSnapshot, SessionNotFoundError | SessionStaleWriteError | MaterializeValidationFailedError | MaterializeWriteFailedError | PathPolicyViolationError | InProcessLockConflictError | BackendCapabilityUnavailableError>>;
   closeSession(input: {
     sessionId: string;
   }): Promise<BackendResult<{
@@ -421,4 +491,4 @@ declare class BackendRuntime {
   refreshCache(input: RefreshCacheInput): BackendResult<BackendJobSnapshot, SessionNotFoundError>;
 }
 //#endregion
-export { BackendSuccess as A, OpenProjectSessionInput as B, BackendJobProgress as C, BackendRuntime as D, BackendResult as E, GetEventsInput as F, BACKEND_CAPABILITY_SCHEMA_VERSION as G, SavePartialFailureError as H, GetEventsSnapshot as I, BackendDiagnostic as J, BACKEND_COMPATIBILITY_POLICY as K, GetJobInput as L, CancelJobInput as M, EventCursorInvalidError as N, BackendRuntimeOptions as O, GetCacheSnapshotInput as P, InProcessLockConflictError as R, BackendJobNotFoundError as S, BackendJobStatus as T, SessionNotFoundError as U, RefreshCacheInput as V, SessionStaleWriteError as W, BackendResponseMeta as X, BackendMessage as Y, BackendStage as Z, BackendJobErrors as _, BackendCacheSnapshot as a, BackendJobListStatusFilter as b, BackendCapabilityUnavailableError as c, BackendEventKind as d, BackendFailure as f, BackendHostAdapter as g, BackendFileSystem as h, BackendCacheEntry as i, CacheRefreshFailedError as j, BackendSessionSnapshot as k, BackendError as l, BackendFileStat as m, ApplySessionTransactionInput as n, BackendCapabilities as o, BackendFileHandle as p, BACKEND_CONTRACT_VERSION as q, BackendArtifactBridgeCapability as r, BackendCapabilityManifest as s, AdvisoryLockConflictError as t, BackendEvent as u, BackendJobKind as v, BackendJobSnapshot as w, BackendJobNotCancellableError as x, BackendJobListSnapshot as y, ListJobsInput as z };
+export { BACKEND_CONTRACT_VERSION as $, BackendSessionSnapshot as A, ListJobsInput as B, BackendJobProgress as C, BackendResult as D, BackendProjectSessionStorage as E, GetCacheSnapshotInput as F, OpenProjectSessionInput as G, MaterializeSessionSnapshot as H, GetEventsInput as I, SaveSessionInput as J, RefreshCacheInput as K, GetEventsSnapshot as L, CacheRefreshFailedError as M, CancelJobInput as N, BackendRuntime as O, EventCursorInvalidError as P, BACKEND_COMPATIBILITY_POLICY as Q, GetJobInput as R, BackendJobNotFoundError as S, BackendJobStatus as T, MaterializeValidationFailedError as U, MaterializeSessionInput as V, MaterializeWriteFailedError as W, SessionStaleWriteError as X, SessionNotFoundError as Y, BACKEND_CAPABILITY_SCHEMA_VERSION as Z, BackendJobErrors as _, BackendCacheSnapshot as a, BackendJobListStatusFilter as b, BackendCapabilityUnavailableError as c, BackendEventKind as d, BackendDiagnostic as et, BackendFailure as f, BackendHostAdapter as g, BackendFileSystem as h, BackendCacheEntry as i, BackendSuccess as j, BackendRuntimeOptions as k, BackendError as l, BackendFileStat as m, ApplySessionTransactionInput as n, BackendResponseMeta as nt, BackendCapabilities as o, BackendFileHandle as p, SavePartialFailureError as q, BackendArtifactBridgeCapability as r, BackendStage as rt, BackendCapabilityManifest as s, AdvisoryLockConflictError as t, BackendMessage as tt, BackendEvent as u, BackendJobKind as v, BackendJobSnapshot as w, BackendJobNotCancellableError as x, BackendJobListSnapshot as y, InProcessLockConflictError as z };