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

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

@@ -95,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;
@@ -119,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;
@@ -190,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;
@@ -242,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;
@@ -373,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;
@@ -384,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;
@@ -415,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<{
@@ -434,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 };

package/dist/{runtime-DlM27Izm.d.cts → runtime-Jec6FcF5.d.cts}

@@ -95,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;
@@ -119,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;
@@ -190,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;
@@ -242,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;
@@ -373,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;
@@ -384,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;
@@ -415,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<{
@@ -434,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 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openfairygui/backend",
-  "version": "0.2.0-alpha.6",
+  "version": "0.2.0-alpha.8",
   "description": "FairyGUI Headless Authoring SDK — stateful backend runtime and session services.",
   "author": "OpenFairyGUI Contributors",
   "license": "MIT",
@@ -52,8 +52,8 @@
     "runtime"
   ],
   "dependencies": {
-    "@openfairygui/core": "0.2.0-alpha.6",
-    "@openfairygui/functions": "0.2.0-alpha.6"
+    "@openfairygui/core": "0.2.0-alpha.8",
+    "@openfairygui/functions": "0.2.0-alpha.8"
   },
   "devDependencies": {
     "ava": "^7.0.0",

package/src/index.ts

@@ -38,12 +38,24 @@ export {
 	type GetJobInput,
 	type InProcessLockConflictError,
 	type ListJobsInput,
+	type MaterializeSessionInput,
+	type MaterializeSessionSnapshot,
+	type MaterializeValidationFailedError,
+	type MaterializeWriteFailedError,
 	type OpenProjectSessionInput,
+	type BackendProjectSessionStorage,
 	type RefreshCacheInput,
+	type SaveSessionInput,
 	type SavePartialFailureError,
 	type SessionNotFoundError,
 	type SessionStaleWriteError,
 } from './runtime.js';
+export {
+	createBackendStorageFileSystem,
+	type BackendAsyncStorageAdapter,
+	type BackendStorageFileSystem,
+	type BackendStorageStatLike,
+} from './storage.js';
 export {
 	type BackendDiagnostic,
 	type BackendMessage,

package/src/runtime.ts

@@ -66,7 +66,13 @@ export 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;
@@ -98,6 +104,7 @@ export interface BackendCapabilities {
 		'getSession',
 		'applyTransaction',
 		'saveSession',
+		'materializeSession',
 		'closeSession',
 		'getEvents',
 		'getJob',
@@ -178,6 +185,16 @@ export interface BackendSessionSnapshot {
 	capabilities: BackendCapabilities;
 }
 
+export interface MaterializeSessionSnapshot extends BackendSessionSnapshot {
+	mode: 'fullProject';
+	reason?: string;
+	materializeRevision: number;
+	saveRevision: number;
+	writtenPaths: string[];
+	skippedPaths: string[];
+	diagnostics: import('./contracts.js').BackendDiagnostic[];
+}
+
 export interface BackendSuccess<T> {
 	ok: true;
 	meta: BackendResponseMeta;
@@ -238,6 +255,29 @@ export interface SavePartialFailureError {
 	diskMayBePartiallyUpdated: true;
 }
 
+export interface MaterializeValidationFailedError {
+	code: 'materialize_validation_failed';
+	message: string;
+	sessionId: string;
+	canonicalPathKey: string;
+	issueCount: number;
+	diagnostics: import('./contracts.js').BackendDiagnostic[];
+}
+
+export interface MaterializeWriteFailedError {
+	code: 'write_failed';
+	message: string;
+	sessionId: string;
+	canonicalPathKey: string;
+	attemptedRevision: number;
+	lastSavedRevision: number;
+	writtenPaths: string[];
+	failedPaths: string[];
+	skippedPaths: string[];
+	diagnostics: import('./contracts.js').BackendDiagnostic[];
+	diskMayBePartiallyUpdated: true;
+}
+
 export type BackendEventKind =
 	| 'session.opened'
 	| 'transaction.applied'
@@ -418,6 +458,8 @@ export type BackendError =
 	| InProcessLockConflictError
 	| AdvisoryLockConflictError
 	| SavePartialFailureError
+	| MaterializeValidationFailedError
+	| MaterializeWriteFailedError
 	| PathPolicyViolationError
 	| EventCursorInvalidError
 	| BackendJobNotFoundError
@@ -438,6 +480,33 @@ export interface OpenProjectSessionInput {
 	sessionId?: string;
 	canonicalProjectPath?: string;
 	canonicalPathKey?: string;
+	storage?: BackendProjectSessionStorage;
+}
+
+export interface BackendProjectSessionStorage {
+	fileSystem: BackendFileSystem;
+	fairyPath: string;
+	canonicalProjectPath?: string;
+	canonicalPathKey?: string;
+}
+
+export interface SaveSessionInput {
+	sessionId: string;
+	expectedRevision?: number;
+	targetPath?: string;
+	fileSystem?: BackendFileSystem;
+	force?: boolean;
+	mode?: 'materializeCleanSession';
+}
+
+export interface MaterializeSessionInput {
+	sessionId: string;
+	expectedRevision?: number;
+	storage?: BackendProjectSessionStorage;
+	targetPath?: string;
+	fileSystem?: BackendFileSystem;
+	mode?: 'fullProject';
+	reason?: string;
 }
 
 export interface BackendRuntimeOptions {
@@ -452,6 +521,7 @@ const BACKEND_METHODS = [
 	'getSession',
 	'applyTransaction',
 	'saveSession',
+	'materializeSession',
 	'closeSession',
 	'getEvents',
 	'getJob',
@@ -502,7 +572,13 @@ function createCapabilities(): BackendCapabilities {
 			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,
@@ -628,23 +704,37 @@ export class BackendRuntime {
 		return this.authoringService.applyTransaction(input);
 	}
 
-	public async saveSession(input: {
-		sessionId: string;
-		expectedRevision?: number;
-		targetPath?: string;
-	}): Promise<
+	public async saveSession(input: SaveSessionInput): Promise<
 		BackendResult<
-			BackendSessionSnapshot,
+			BackendSessionSnapshot | MaterializeSessionSnapshot,
 			| SessionNotFoundError
 			| SessionStaleWriteError
 			| SavePartialFailureError
+			| MaterializeValidationFailedError
+			| MaterializeWriteFailedError
 			| PathPolicyViolationError
+			| InProcessLockConflictError
 			| BackendCapabilityUnavailableError
 		>
 	> {
 		return this.authoringService.saveSession(input);
 	}
 
+	public async materializeSession(input: MaterializeSessionInput): Promise<
+		BackendResult<
+			MaterializeSessionSnapshot,
+			| SessionNotFoundError
+			| SessionStaleWriteError
+			| MaterializeValidationFailedError
+			| MaterializeWriteFailedError
+			| PathPolicyViolationError
+			| InProcessLockConflictError
+			| BackendCapabilityUnavailableError
+		>
+	> {
+		return this.authoringService.materializeSession(input);
+	}
+
 	public async closeSession(input: {
 		sessionId: string;
 	}): Promise<BackendResult<{ sessionId: string; closed: true }, SessionNotFoundError>> {