From 0e0cdf4f6709e94284c275c2515e1899fee4d331 Mon Sep 17 00:00:00 2001
From: Zac White <zac@velosmobile.com>
Date: Thu, 23 Apr 2026 21:16:49 -0700
Subject: [PATCH] Expose immutable workspace filesystem

---
 README.md                            |  9 +++++++++
 Sources/Workspace/Workspace.swift    |  6 +++++-
 Tests/WorkspaceTests/CoreTests.swift | 13 +++++++++++++
 3 files changed, 27 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 40319b7..f5f4ffe 100644
--- a/README.md
+++ b/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
diff --git a/Sources/Workspace/Workspace.swift b/Sources/Workspace/Workspace.swift
index 4459a68..8844684 100644
--- a/Sources/Workspace/Workspace.swift
+++ b/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?
 
diff --git a/Tests/WorkspaceTests/CoreTests.swift b/Tests/WorkspaceTests/CoreTests.swift
index 706e928..83ba09f 100644
--- a/Tests/WorkspaceTests/CoreTests.swift
+++ b/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()