@@ -0,0 +1,71 @@
+//
+//  CodeFileDocument+ExternalChanges.swift
+//  CodeEdit
+//
+//  Created by Matthijs Eikelenboom on 22/08/26.
+//
+
+import AppKit
+
+/// Reacting to the file changing underneath us on disk.
+///
+/// **The isolation here is a bridge, not a resolution.** `NSDocument` is main-actor isolated but
+/// declares `read(from:ofType:)` and `presentedItemDidChange()` nonisolated, so both override a
+/// nonisolated entry point while touching main-actor document state. `MainActor.assumeIsolated`
+/// states an invariant the compiler cannot check, and the `Thread.isMainThread` branch below
+/// substitutes a runtime test for a static guarantee.
+///
+/// The underlying problem is that ``CodeFileDocument`` mixes main-actor UI state (`content` is an
+/// `NSTextStorage` SwiftUI observes) with an I/O lifecycle AppKit drives from arbitrary threads.
+/// The proper fix separates the two: decode into a `Sendable` value with no isolation, then install
+/// it in one main-actor step. That is a redesign of the document's state ownership, deliberately
+/// deferred. See `docs/architecture-decisions.md`, "Document isolation is bridged, not solved".
+extension CodeFileDocument {
+    /// Handle the notification that the represented file item changed.
+    ///
+    /// We check if a file has been modified and can be read again to display to the user.
+    /// To determine if a file has changed, we check the modification date. If it's different from the stored one,
+    /// we continue.
+    /// To determine if we can reload the file, we check if the document has outstanding edits. If not, we reload the
+    /// file.
+    override public func presentedItemDidChange() {
+        // Unlike reads, this genuinely arrives on the file-presenter thread, while the state it
+        // consults is main-actor isolated. This blocks the presenter thread intentionally: if we
+        // don't wait, we'll receive more updates that the file has changed and end up dispatching
+        // multiple reads. The presenter thread expects this to be synchronous anyway.
+
+        // https://github.com/CodeEditApp/CodeEdit/issues/2091
+        // We can't use `.asyncAndWait` on Ventura as it seems the symbol is missing on that
+        // platform. Could be just for x86 machines.
+        let reloadIfClean: @MainActor () -> Bool = { [self] in
+            guard fileModificationDate != getModificationDate(), !isDocumentEdited else {
+                return false
+            }
+            fileModificationDate = getModificationDate()
+            if let fileURL, let fileType {
+                try? read(from: fileURL, ofType: fileType)
+            }
+            return true
+        }
+
+        // Callers are not all off-main: `NSFileCoordinator` delivers on the presenter thread, but
+        // tests (and any future in-process caller) may already be on the main thread, where
+        // `DispatchQueue.main.sync` would deadlock. Mirrors the branch in ``notifyLSPDidOpen()``.
+        let handled = Thread.isMainThread
+            ? MainActor.assumeIsolated { reloadIfClean() }
+            : DispatchQueue.main.sync { MainActor.assumeIsolated { reloadIfClean() } }
+
+        if !handled {
+            super.presentedItemDidChange()
+        }
+    }
+
+    /// Helper to find the last modified date of the represented file item.
+    /// 
+    /// Different from `NSDocument.fileModificationDate`. This returns the *current* modification date, whereas the
+    /// alternative stores the date that existed when we last read the file.
+    private func getModificationDate() -> Date? {
+        guard let path = fileURL?.absolutePath else { return nil }
+        return try? FileManager.default.attributesOfItem(atPath: path)[.modificationDate] as? Date
+    }
+}
@@ -165,6 +165,16 @@ public final class CodeFileDocument: NSDocument, ObservableObject {
 
     // MARK: - Read
 
+    /// Never read concurrently.
+    ///
+    /// This is AppKit's default, stated explicitly because ``read(from:ofType:)`` depends on it:
+    /// that method overrides a nonisolated `NSDocument` entry point but touches this document's
+    /// main-actor state, which is only sound while reads stay on the main thread. Returning `true`
+    /// here would make that unsound with no compile-time error.
+    override public static func canConcurrentlyReadDocuments(ofType typeName: String) -> Bool {
+        false
+    }
+
     /// This function is used for decoding files.
     /// It should not throw error as unsupported files can still be opened by QLPreviewView.
     override public func read(from data: Data, ofType _: String) throws {
@@ -183,14 +193,20 @@ public final class CodeFileDocument: NSDocument, ObservableObject {
             Self.logger.error("Failed to read file from data using encoding: \(rawEncoding)")
             return
         }
-        self.sourceEncoding = validEncoding
-        if let content {
-            registerContentChangeUndo(fileURL: fileURL, nsString: nsString, content: content)
-            content.mutableString.setString(nsString as String)
-        } else {
-            self.content = NSTextStorage(string: nsString as String)
+        // `read(from:ofType:)` overrides a nonisolated `NSDocument` method, but everything below
+        // touches main-actor state. Reads are main-thread only, which
+        // `canConcurrentlyReadDocuments(ofType:)` above pins, so stating the isolation is sound.
+        let text = nsString as String
+        MainActor.assumeIsolated {
+            self.sourceEncoding = validEncoding
+            if let content {
+                registerContentChangeUndo(fileURL: fileURL, text: text, content: content)
+                content.mutableString.setString(text)
+            } else {
+                self.content = NSTextStorage(string: text)
+            }
+            notifyLSPDidOpen()
         }
-        notifyLSPDidOpen()
     }
 
     /// The delegate is main-actor isolated, but document reads and closes can happen off the main
@@ -219,12 +235,12 @@ public final class CodeFileDocument: NSDocument, ObservableObject {
     /// - Note: This is inefficient memory-wise. We could do a diff of the file and only register the
     ///         mutations that would recreate the diff. However, that would instead be CPU intensive.
     ///         Tradeoffs.
-    nonisolated private func registerContentChangeUndo(fileURL: URL?, nsString: NSString, content: NSTextStorage) {
+    nonisolated private func registerContentChangeUndo(fileURL: URL?, text: String, content: NSTextStorage) {
         guard let fileURL else { return }
         // The delegate's undo registry is main-actor isolated. Capture only Sendable primitives and build
         // the (non-Sendable) `TextMutation` on the main actor so nothing non-Sendable crosses the boundary.
         // Re-reads reach here on the main thread; mirror the `queue: .main` bridge used for LSP notifications.
-        let string = nsString as String
+        let string = text
         let length = content.length
         let register: @MainActor () -> Void = { [weak self] in
             let mutation = TextMutation(
@@ -295,47 +311,6 @@ public final class CodeFileDocument: NSDocument, ObservableObject {
         }
     }
 
-    // MARK: - External Changes
-
-    /// Handle the notification that the represented file item changed.
-    ///
-    /// We check if a file has been modified and can be read again to display to the user.
-    /// To determine if a file has changed, we check the modification date. If it's different from the stored one,
-    /// we continue.
-    /// To determine if we can reload the file, we check if the document has outstanding edits. If not, we reload the
-    /// file.
-    override public func presentedItemDidChange() {
-        if fileModificationDate != getModificationDate() {
-            guard isDocumentEdited else {
-                fileModificationDate = getModificationDate()
-                if let fileURL, let fileType {
-                    // This blocks the presented item thread intentionally. If we don't wait, we'll receive more updates
-                    // that the file has changed and we'll end up dispatching multiple reads.
-                    // The presented item thread expects this operation to by synchronous anyways.
-
-                    // https://github.com/CodeEditApp/CodeEdit/issues/2091
-                    // We can't use `.asyncAndWait` on Ventura as it seems the symbol is missing on that platform.
-                    // Could be just for x86 machines.
-                    DispatchQueue.main.sync {
-                        try? self.read(from: fileURL, ofType: fileType)
-                    }
-                }
-                return
-            }
-        }
-
-        super.presentedItemDidChange()
-    }
-
-    /// Helper to find the last modified date of the represented file item.
-    /// 
-    /// Different from `NSDocument.fileModificationDate`. This returns the *current* modification date, whereas the
-    /// alternative stores the date that existed when we last read the file.
-    private func getModificationDate() -> Date? {
-        guard let path = fileURL?.absolutePath else { return nil }
-        return try? FileManager.default.attributesOfItem(atPath: path)[.modificationDate] as? Date
-    }
-
     // MARK: - Close
 
     override public func close() {
 
@@ -129,4 +129,26 @@ The first seven are process-scoped services that simply have not moved to `AppDe
 `TerminalCache` is different, and is the one worth fixing rather than relocating.
 It is a process-global `[UUID: CELocalShellTerminalView]` holding views that belong to a workspace window.
 Eviction is per-terminal only, and nothing clears it when a workspace or window closes, so two open projects share one bag of live terminal views.
-It works because UUIDs do not collide, but the lifetime is wrong, and a wrong lifetime surfaces as a leak rather than as a compile error.
+It works because UUIDs do not collide, but the lifetime is wrong, and a wrong lifetime surfaces as a leak rather than as a compile error.
+
+## Document isolation is bridged, not solved
+
+`CodeFileDocument` moved into `CodeEditDocument` during the package extraction, which put it under Swift 6 strict concurrency for the first time.
+That surfaced six pre-existing isolation errors, all in code that is byte-identical on `main` and compiles silently there.
+
+`NSDocument` is main-actor isolated, but declares `read(from:ofType:)` and `presentedItemDidChange()` nonisolated, because AppKit may call them off the main thread.
+Both touch main-actor document state.
+Three things now hold that together, and none of them is a static guarantee:
+
+1. `canConcurrentlyReadDocuments(ofType:)` is overridden to return `false`, pinning AppKit's default so reads stay on the main thread. Returning `true` would make the isolation unsound with no compile error.
+2. `read(from:ofType:)` uses `MainActor.assumeIsolated`, which relies on (1).
+3. `presentedItemDidChange()` branches on `Thread.isMainThread`, because it genuinely arrives on the file-presenter thread in production but on the main thread from tests. An unconditional `DispatchQueue.main.sync` deadlocks the second case.
+
+This is accepted as a bridge so the extraction can land, not as the end state.
+The real problem is that the type mixes main-actor UI state (`content` is an `NSTextStorage` that SwiftUI observes) with an I/O lifecycle driven from arbitrary threads.
+Separating those, so decoding produces a `Sendable` value that a single main-actor step installs, removes all three props at once.
+That is a redesign of the document's state ownership and is deliberately deferred.
+
+The general lesson is worth stating separately, because it applies to every future extraction: **moving a file into `CodeEditModules` is also a Swift 6 migration of that file.**
+The app target is `SWIFT_VERSION = 5.0` with no `SWIFT_STRICT_CONCURRENCY` setting, so it defaults to `minimal`; the package is `swift-tools-version: 6.0`, so every target defaults to Swift 6 language mode.
+Code that compiled without complaint for years can arrive in a package with a dozen errors, none of them regressions.