Add immutable filesystem access on Workspace

README.md

@@ -77,6 +77,15 @@ let filesystem = InMemoryFilesystem()
 let workspace = Workspace(filesystem: filesystem)
 ```
 
+After a workspace is created, `workspace.filesystem` exposes the backing filesystem as a normal
+`FileSystem`. The property itself is immutable, but the returned filesystem keeps its read/write
+capabilities:
+
+```swift
+let filesystem: any FileSystem = workspace.filesystem
+let data = try await filesystem.readFile(path: "/notes/todo.txt")
+```
+
 Persist checkpoint artifacts with file-backed storage:
 
 ```swift

Sources/Workspace/Workspace.swift

@@ -24,7 +24,11 @@ public actor Workspace {
 
     public nonisolated let workspaceId: UUID
 
-    let filesystem: any FileSystem
+    /// The workspace's backing filesystem.
+    ///
+    /// The property is immutable after initialization, but the returned filesystem retains its normal
+    /// ``FileSystem`` capabilities.
+    public nonisolated let filesystem: any FileSystem
     let store: any CheckpointStore
     let baseCheckpointId: UUID?
 

Tests/WorkspaceTests/CoreTests.swift

@@ -327,6 +327,19 @@ struct CoreTests {
         #expect(error.description.contains("workspace shim check"))
     }
 
+    @Test
+    func `workspace exposes immutable filesystem property`() async throws {
+        let workspace = Workspace(filesystem: InMemoryFilesystem())
+
+        try await workspace.writeFile("/note.txt", content: "hello")
+
+        let filesystem: any FileSystem = workspace.filesystem
+        #expect(try await filesystem.readFile(path: "/note.txt") == Data("hello".utf8))
+
+        try await filesystem.writeFile(path: "/direct.txt", data: Data("normal".utf8), append: false)
+        #expect(try await workspace.readFile("/direct.txt") == "normal")
+    }
+
     @Test
     func `readJSON and writeJSON roundtrip`() async throws {
         let fs = InMemoryFilesystem()