DEV Community: Muhittin Çamdalı

SwiftUI Document API: ReadableDocument and WritableDocument

Muhittin Çamdalı — Mon, 26 Oct 2026 08:53:18 +0000

SwiftUI's Document API got a fundamental update with iOS 27: Apple introduced two new protocols for document-based apps, ReadableDocument and WritableDocument. In this post I walk through the difference between these protocols and FileDocument/ReferenceFileDocument, the incremental/asynchronous write mechanism, and the multi-document creation flow with DocumentCreationSource, step by step, based on Apple's WWDC26 resources and an independent write-up that corroborates them.

💡 Pro Tip: If you're starting a project whose new deployment target is 27+, start directly with ReadableDocument/WritableDocument instead of FileDocument — migrating back later is far more expensive than starting there.

Why the new protocols arrived

Apple's official WWDC26 guide describes the expanded SwiftUI Document API this way: "The expanded SwiftUI Document API gives you direct control over the structure of your saved documents. For reading and writing, conform to WritableDocument and ReadableDocument…" This sentence sums up the origin point of the new protocols: the old FileDocument/ReferenceFileDocument pair didn't give you fine-grained control over the document's structure on disk.

Apple's WWDC26 session 269 walkthrough directly backs up the same motivation: "First, the write method is nonisolated and asynchronous. This lets me perform expensive disk writing operations in the background, so the app stays responsive. I write only the parts of the package that actually need updating, by comparing the current and the previous snapshots." So the reason isn't one thing: disk-structure control, incremental writes, and non-blocking background I/O.

On top of that, the new Document type is now a reference type marked @Observable. In onmyway133's words: "The document is a reference type marked @observable, so SwiftUI does not recreate it on every change."

The WWDC26 guide page doesn't quote FileDocument directly, but Apple's session 269 summary explicitly mentions this protocol: "Expanded document APIs for SwiftUI apps, including the new DocumentCreationSource API for custom new-document flows, performance improvements for reading and writing large documents, and first-class support for direct document URL access via the FileDocument and ReferenceFileDocument protocols." onmyway133's write-up summarizes this more sharply: "two new protocols replace FileDocument and ReferenceFileDocument for new code." So the new protocols are a pair that replaces the old ones for newly written code — a distinction that matters later (specifically, in the iOS 26 compatibility section).

Migrating FileDocument → ReadableDocument (a side-by-side example)

The StickerDocument definition below, based on the WWDC26 session's example, shows what conforming to WritableDocument looks like.

ReadableDocument is defined in the WWDC26 session like this: "ReadableDocument is a twin to WritableDocument. Here's how they compare. Each protocol requires a list of supported content types. WritableDocument provides a snapshot and ReadableDocument knows how to apply it." The same session clarifies disk access this way: "ReadableDocument's friend is DocumentReader, which does all the disk-related heavy lifting." So it works on a twin-protocol model, and applying snapshots read from disk back onto the document is handled through a DocumentReader that owns that job.

@Observable
final class StickerDocument: WritableDocument {
    static let writableContentTypes: [UTType] = [.stickerDocument]

    @MainActor
    func snapshot(contentType: UTType) async throws -> sending PageSnapshot {
        // encode current state into a PageSnapshot
    }

    func writer(configuration: sending WriteConfiguration) -> sending Writer {
        // return a Writer that knows how to persist a PageSnapshot
    }
}

The @MainActor marking on the definition above shows that taking a snapshot runs on the main thread; the nonisolated marking you'll see on the write side further down shows the opposite — that operation can run without being tied to any actor.

What the old FileDocument side used to look like

To complete this "side-by-side example" comparison, the same StickerDocument type's conformance to the old FileDocument protocol used to look like this — a struct that declares readableContentTypes, does reading in a single pass inside init(configuration:), and writing in a single pass inside fileWrapper(configuration:):

struct StickerDocument: FileDocument {
    static var readableContentTypes: [UTType] { [.stickerDocument] }

    init(configuration: ReadConfiguration) throws {
        // decode the data inside configuration.file (a FileWrapper) into the struct in one pass
    }

    func fileWrapper(configuration: WriteConfiguration) throws -> FileWrapper {
        // encode the struct's current state into a new FileWrapper in one pass
    }
}

Side by side with the WritableDocument example above, the difference is clear: the old side runs init(configuration:) and fileWrapper(configuration:) synchronously in one piece, while the new side prepares snapshot(contentType:) on @MainActor and pushes the actual disk write through a separate, nonisolated writer (shown further down).

The role of PageSnapshot and DocumentReader

In the WWDC26 session 269 example, the type returned by snapshot(contentType:) above is concretely defined as: struct PageSnapshot { var background: Image; var metadata: StickerPlacements; var stickers: [Image] }. So the snapshot freezes the document's state — background image, metadata with sticker positions, and the sticker images — into one value type; ReadableDocument's apply(snapshot:previous:) applies this PageSnapshot, read back from disk, onto the document object.

In the same session, StickerDocument's conformance to ReadableDocument is given as a separate extension: extension StickerDocument: ReadableDocument {}. This shows that WritableDocument and ReadableDocument can be defined as two separate conformance blocks on the same class — meaning reading and writing responsibilities can be separated in the code itself as well.

The real difference in a practical migration: FileDocument was a value type (struct), so every read produced a new copy; on ReadableDocument, you're applying a snapshot to a reference-type, @Observable document object instead. Migration isn't "change the protocol signature" — it's moving the document model from value to reference.

The most concrete consequence of this shift shows up in the SwiftUI view layer. onmyway133's statement — "so SwiftUI does not recreate it on every change, and a TextEditor bound to a document property does not lose its model on each keystroke" — shows this directly: once ReadableDocument moves to a reference type, the document object's identity is preserved even when the view redraws, so a TextEditor bound to the document property doesn't lose its model on every keystroke.

Dimension	FileDocument (old)	ReadableDocument (new)
Type nature	Value (struct)	Reference, `@Observable`
Read responsibility	In one pass, inside `init(configuration:)`	Applying a snapshot via `DocumentReader`
Recreation on change	New struct copy on every edit	Object identity preserved, not recreated
Content type declaration	`static var readableContentTypes`	`readableContentTypes`, `reader(configuration:)`, `apply(snapshot:previous:)`

ReferenceFileDocument → WritableDocument

ReferenceFileDocument was already a reference type, so moving to WritableDocument is conceptually less of a leap than the ReadableDocument migration.

onmyway133's point brings clarity here: "You convert between your data and disk through a snapshot, using either the FileWrapperDocumentReader and FileWrapperDocumentWriter convenience types or a fully custom reader and writer for streaming or direct URL access." So on the WritableDocument side, the data conversion now happens through a snapshot, either via a concrete convenience type like FileWrapperDocumentWriter or through a fully custom reader/writer — conceptually corresponding to ReferenceFileDocument's snapshot(contentType:) + fileWrapper(snapshot:configuration:) pair, but with disk access now extended with streaming/direct URL support.

Feature	ReferenceFileDocument (old)	WritableDocument (new)
Type nature	Reference (class), `ObservableObject`	Reference, `@Observable`
Write helper type	`fileWrapper(snapshot:configuration:)`	`FileWrapperDocumentWriter` / `DocumentWriter`
Disk access	Single-shot `FileWrapper` production	Streaming or direct URL support
Progress reporting	Not specified	`Subprogress` parameter

A concrete Writer type

WWDC26 session 269 gives a concrete writer type that conforms to DocumentWriter like this: struct Writer<Snapshot>: DocumentWriter { typealias Snapshot = PageSnapshot; let contentType: UTType }. So Writer is a generic helper type that knows which PageSnapshot to write for which contentType; the WritableDocument.writer(configuration:) method returns an instance of this type every time it's called.

Exporting the same document as PNG too

In the same session, the content types Writer supports aren't limited to a single format. Around 14:35, .png is added to the writableContentTypes list; at 14:48, the writer branches on it like this: if contentType.conforms(to: .stickerDocument) { /* write the .stickerDocument package */ } else if contentType.conforms(to: .png) { /* write the flattened image for .png */ }. So the same Writer, by checking the contentType parameter, can produce either the document's own package format (.stickerDocument) or a flattened PNG output — this is the branch that kicks in for exporting the page visually.

Incremental and asynchronous writing

Computing the diff with the previous parameter

The signature in the WWDC26 session's code example shows directly how incremental writing works: DocumentWriter.write(snapshot:to:previous:progress:). The previous parameter here carries the prior state into the writer; this lets the writer write only the part that changed, not the whole document.

nonisolated func write(
    snapshot: sending PageSnapshot,
    to destination: URL,
    previous: sending PageSnapshot?,
    progress: consuming Subprogress
) async throws {
    // write .stickerDocument
    // previous == nil  → first save, full write
    // previous != nil  → only the diff is written (incremental write)
}

Apple's session 269 walkthrough directly confirms this: the write compares current and previous snapshots and applies only to the package parts that actually need updating, running in the background without blocking the main thread — so incremental writing isn't just "write less data," it's also "don't keep the UI thread busy."

In practice: in a large document (say, a drawing file with dozens of pages), every Cmd+S now writes to disk only the parts that changed since the last operation, not the entire document.

Progress reporting with Subprogress

The progress: consuming Subprogress parameter you saw in the signature above is Foundation's progress-reporting API integrated directly into the SwiftUI Document layer. The WWDC26 guide summarizes it this way: "offer asynchronous, incremental disk operations and progress reporting via the Foundation Subprogress API." onmyway133 confirms the same point: "Packages can be read and written incrementally, and progress flows through Subprogress." — two independent sources agree here.

The consuming keyword shows that the Subprogress value is handed over (ownership transfer) to the write call — meaning the writer reports the progress of its own sub-operations back up to the caller through this single parameter. This means that when you want to show the user something like "42% saved" while saving a large document, you don't need to manually synchronize your own progress counters; the framework carries that for you.

What the consuming keyword means

// The result from the signature (verified in WWDC26): consuming Subprogress
// "consuming" → the value is handed over to the write() call, ownership never returns.
// Practical effect: you don't need to update progress by hand,
// DocumentWriter reports its own sub-operations' progress through this parameter.

DocumentCreationSource and NewDocumentButton

The WWDC26 guide defines this feature in one clear sentence: "The DocumentCreationSource API lets you declare multiple creation sources with a NewDocumentButton for each." So instead of one "New Document" button, an app can now define multiple buttons, each for a different starting state (blank page, template, import from photo, and so on).

The literal call from the WWDC26 session's code example is this:

extension DocumentCreationSource {
    static let blank = Self(id: "blank")
    static let photo = Self(id: "photo")
}

DocumentGroupLaunchScene("Create a Sticker Page") {
    NewDocumentButton("New Sticker Page", source: .blank)
    NewDocumentButton("Sticker Page from Photo…", source: .photo)
}

Adding multiple sources to the scene

The pattern is clear: each source is a static DocumentCreationSource value initialized with an id string, and NewDocumentButton takes a title string plus this value. The buttons' layout in the scene is just as clear: multiple NewDocumentButtons are defined one after another inside DocumentGroupLaunchScene, each carrying its own source. In practice: a drawing app with two flows like "Blank Page" and "Start from Photo" means two separate NewDocumentButton lines, each with a different source value.

iCloud/Files integration pitfalls

There's a broadly applicable pitfall to keep in mind when thinking about iCloud or Files syncing, confirmed in onmyway133's write-up: "One thing to remember is that SwiftUI tracks unsaved changes through undo actions, so without registered undo actions it will not autosave." In other words, SwiftUI tracks unsaved changes through undo actions. If a change hasn't been registered on the undo stack, autosave isn't triggered.

Why autosave doesn't trigger without a registered undo action

The practical consequence of this is: if you mutate your document by directly assigning to an @Observable property (without registering an undo action), SwiftUI doesn't mark that change as "unsaved" and won't autosave it — the file stays in its old state on disk (and therefore in iCloud sync too). That's why every mutation needs to go through a registered action via UndoManager; otherwise the change appears to the user as if it's "lost," when in fact it was never written at all.

iOS 26 backward compatibility

Apple's canonical documentation data is clear: the new protocols ship only with iOS 27.0, iPadOS 27.0, Mac Catalyst 27.0, macOS 27.0, and visionOS 27.0 (per the platform records in readabledocument.json and writabledocument.json) — not backported to iOS 26. The old FileDocument and ReferenceFileDocument have existed since iOS 14.0 / macOS 11.0; as of publish date, a mixed deployment target (one also covering below 27) has to stay on these protocols, since the new ones don't run there.

The consequence is this: if your deployment target is 27+, onmyway133's write-up gives clear advice — "If you are starting a document app today and your deployment target is 27 or later, reach for these rather than the older protocols." With a mixed deployment target (iOS 26+27), staying on the old API isn't a preference, it's a requirement — the new protocols don't exist on iOS 26.

What to do with a mixed deployment target

This advice needs to be read together with the onmyway133-sourced "replace ... for new code" statement from the "Why the new protocols arrived" section above: the new protocols replace the old ones for newly written code, but since the old ones are still usable as of publish date, an app with a mixed deployment target can host both protocol families at once — one for the 27+ flow, the other for backward compatibility.

🏆 GOLDEN TIP: Don't make the migration a "big bang"

The biggest mistake when moving to the new protocols is changing the entire document model in one commit. Instead, move the read-only side to ReadableDocument first and leave writing on the old fileWrapper path a while longer — you can test the two sides separately. Verify the undo-based autosave behavior (the pitfall above) only after moving the write side, with real user flows — it never shows up on the read side, and the surprise usually hits on the first real "save." I prefer starting with the smallest, least critical document type, so you learn the framework's async/incremental behavior in a low-risk module, not in production.

Checklist

If you've read this far, you've earned an ordered checklist you can follow when moving to the new Document API. The items below gather the sourced pitfalls and steps from this post into a single sequence — check each one off before you start the migration.

Confirm your deployment target is genuinely 27 or later
Determine whether your document model is a value type or a reference type
Move the ReadableDocument side first, leave WritableDocument for the second step
Write every mutation as a registered action through UndoManager
Test autosave behavior only after you've registered undo actions
For large documents, log and verify that the previous parameter arrives populated
Print Subprogress progress to the console before wiring it to a real UI indicator
If you use multiple NewDocumentButtons, test each one's source value separately

FAQ

What replaces FileDocument now?

With iOS, macOS, and visionOS 27, Apple introduced the ReadableDocument and WritableDocument protocols for document-based SwiftUI apps. In onmyway133's words, these two protocols replace the old FileDocument/ReferenceFileDocument pair ("two new protocols replace FileDocument and ReferenceFileDocument for new code.") and are positioned as the recommended approach for new code.

What's the difference between ReadableDocument and WritableDocument?

ReadableDocument holds the list of supported content types and knows how to apply snapshots read from disk onto the document; this work is carried out via a DocumentReader. WritableDocument provides the list of writable formats and a snapshot mechanism that returns the current content, through a writer type that conforms to DocumentWriter — twin protocols, one carrying the reading responsibility, the other the saving responsibility.

How do I incrementally save a large file in SwiftUI?

WritableDocument's writer takes the prior state via previous in write(snapshot:to:previous:progress:) and writes only the changed part. The same call reports progress via progress: consuming Subprogress — so instead of rewriting large documents from scratch, you save them piece by piece, asynchronously.

How do you define multiple new-document sources in a DocumentGroup?

You define a DocumentCreationSource value for each different starting state and pass it to a NewDocumentButton("Title", source: source) call. The verified call from the WWDC26 code example looks like NewDocumentButton("New Sticker Page", source: .blank); you can reuse the same button type with different source values to offer multiple creation options inside a DocumentGroupLaunchScene.

What happens if I don't register an undo action?

Because SwiftUI tracks unsaved changes through the undo stack, autosave isn't triggered unless a mutation was made as an action registered with UndoManager. This can leave the document looking changed in the UI while staying in its old state on disk — which is why every edit needs to happen inside an undo-aware action.

Do I need to change my old FileDocument code right away?

Not in the short term. FileDocument and ReferenceFileDocument have been usable since iOS 14.0 / macOS 11.0. The new pair ships only with iOS/macOS/visionOS 27.0+, not backported to iOS 26. If your target also covers below 27, staying on the old API is required — the new protocols don't run there. See '## Update (September 2026)' below for a post-publish development on these protocols' status.

Update (September 2026)

After this post's publish date (June 19, 2026), a real change landed in Apple's canonical documentation data: FileDocument and ReferenceFileDocument were marked deprecated as of 27.2. The warning in FileDocument's records reads: "Conform your type to Document instead." ReferenceFileDocument's reads: "Use Document protocol instead." Both protocols had existed since iOS/iPadOS/Mac Catalyst 14.0, macOS 11.0; the deprecation only arrived with 27.2, and isn't a retroactive behavior change.

The Document protocol Apple points to inherits both ReadableDocument and WritableDocument: "Inherits From: ReadableDocument, WritableDocument", with the abstract "A document that supports both reading and writing." (iOS/macOS/visionOS 27.0). So the twin-protocol model this post describes hasn't changed; Document was added on top as a third protocol unifying the two under one name. Read this together with the earlier '## iOS 26 backward compatibility' section: if your deployment target also covers below 27, staying on the old protocols is still required — but it's now "deprecated, yet currently the only option," not "not deprecated."

Conclusion

ReadableDocument and WritableDocument are among the most concrete infrastructure updates SwiftUI has shipped for document-based apps: a reference-type, @Observable document model, incremental/asynchronous writing that reports progress via Subprogress, and multiple document-creation sources via DocumentCreationSource. But this doesn't have to be a "big bang" migration: the new protocols replace the old ones for newly written code, but FileDocument/ReferenceFileDocument are still required for deployment targets that cover below iOS 27; migrating only becomes a choice once your deployment target is 27+ (see the Update section above).

To refresh SwiftUI's state management before moving your document model to a reference type, see my deep dive into SwiftUI property wrappers. Planning a document-based macOS app? The guide to desktop development with SwiftUI on macOS is a natural next step. Curious about other iOS 27 breaking changes? See the post on what broke in the State macro and ContentBuilder. If you're splitting your document model into components, the custom component library guide and, for large-document performance, the performance optimization post are useful references too.

Sources

WWDC26 SwiftUI guide — Apple's official guide; the primary source for ReadableDocument/WritableDocument, Subprogress, and DocumentCreationSource.
What's new in SwiftUI in iOS 27 (onmyway133) — an independent write-up dated June 9, 2026; a second source confirming most items, including the undo-based autosave pitfall.
WWDC26 "What's new in SwiftUI" session video — the session where the DocumentWriter signature and the NewDocumentButton code example appear.
ReadableDocument documentation — the protocol's official reference page.
WritableDocument documentation — the protocol's official reference page.
FileDocument documentation — the old protocol's canonical reference page.
ReferenceFileDocument documentation — the old reference-type protocol's canonical page.
Document protocol documentation — the recommended replacement for FileDocument/ReferenceFileDocument, inheriting ReadableDocument+WritableDocument.
DocumentGroup documentation — the canonical type DocumentCreationSource and NewDocumentButton attach to.
Foundation Subprogress documentation — the Foundation API used for progress reporting.

Originally published at muhittincamdali.com.

App Intents on iOS 27: LongRunningIntent and Siri

Muhittin Çamdalı — Mon, 26 Oct 2026 08:51:57 +0000

iOS 27 brought a major update to the App Intents framework in WWDC26's Session 345: new APIs like LongRunningIntent, CancellableIntent, EntityCollection, and SyncableEntity now make Siri integrations both more resilient and consistent across devices. In this guide I walk through iOS 27 App Intents LongRunningIntent SyncableEntity Siri integration, drawing on WWDC26 Session 345 and Apple's official API documentation, showing what actually changed as of the beta period (June 2026).

💡 Pro Tip: When migrating an existing AppIntent to LongRunningIntent, first wrap your perform() body in a performBackgroundTask block — testing that refactor on its own before adding the protocol makes it much easier to tell which error came from which change.

Why App Intents matters again on iOS 27

The core promise of App Intents hasn't changed: making your app's content and actions discoverable for system experiences like Apple Intelligence, Siri, Spotlight, Shortcuts, and widgets. WWDC26 Session 345 covers the additions from what it calls "our 2027 releases" under eight headings; the documentation lists the same APIs under the "iOS 27.0" tag. I'm focusing on three main axes: long-running work finishing without interruption, no performance loss on large data sets, and entities staying consistent across devices — mapped to LongRunningIntent, EntityCollection, and SyncableEntity respectively; together with CancellableIntent and RelevantEntities I cover these as five core APIs, and the final section is devoted to ExecutionTargets and @UnionValue.

If you haven't touched App Intents fundamentals yet, I'd recommend reading App Intents and Shortcuts integration first — this guide doesn't repeat those fundamentals, it focuses directly on the iOS 27 delta.

Breaking the 30-second wall with LongRunningIntent

According to Apple's official documentation, LongRunningIntent is "an interface you use to extend the background execution time of an app intent that performs a long-running task." The underlying problem: the system traditionally gives a normal intent only up to 30 seconds of run time ("the system traditionally gives it up to 30 seconds to finish its task"). Work like batch photo processing, large file transfers, or a multi-step automation may not finish in that window — in the session, Apple's team describes it exactly as "the intent kept failing because it couldn't finish within the 30-second limit."

On the Swift side, LongRunningIntent is a protocol that extends ProgressReportingIntent (protocol LongRunningIntent : ProgressReportingIntent). ProgressReportingIntent isn't actually a new API — it's been around since iOS 17.0; iOS 27's contribution is combining that progress-reporting infrastructure with LongRunningIntent, which extends background run time.

import AppIntents

struct SyncPhotoLibraryIntent: LongRunningIntent {
    static var title: LocalizedStringResource = "Fotoğrafları Senkronize Et"

    func perform() async throws -> some IntentResult & ReturnsValue<String> {
        let batches = loadBatches()

        let summary = try await performBackgroundTask {
            progress.totalUnitCount = Int64(batches.count)
            for (index, batch) in batches.enumerated() {
                try Task.checkCancellation()
                try await syncBatch(batch)
                progress.completedUnitCount = Int64(index + 1)
            }
            return "\(batches.count) grup senkronize edildi"
        }

        return .result(value: summary)
    }

    private func loadBatches() -> [[String]] { [] }
    private func syncBatch(_ batch: [String]) async throws {}
}

While the work is running, the system automatically shows a Live Activity as progress reports come in, and the user can stop the work from that Live Activity; what's new in iOS 27 is that this Live Activity is triggered automatically by App Intents. If you want to see the mechanism itself in more detail, you can check out interactive widgets and Live Activity.

Writing progress to Live Activity: using the progress object correctly

The most practical thing about LongRunningIntent is that you don't need a manual ActivityKit implementation. What makes that possible is the progress object inherited from ProgressReportingIntent: update totalUnitCount and completedUnitCount, and the system reflects those values in the Live Activity automatically.

Watch how often you update progress. Instead of updating after every single record, update at meaningful stage boundaries (e.g. after each batch) — this avoids needless redraws and gives the user a smoother progress experience:

import AppIntents

struct ProcessRecordsIntent: LongRunningIntent {
    static var title: LocalizedStringResource = "Kayıtları İşle"

    func perform() async throws -> some IntentResult & ReturnsValue<Int> {
        let items = Array(1...250)

        let processedCount = try await performBackgroundTask {
            progress.totalUnitCount = Int64(items.count)
            var processed = 0

            for start in stride(from: 0, to: items.count, by: 25) {
                let chunk = items[start..<min(start + 25, items.count)]
                try await process(Array(chunk))
                processed += chunk.count
                // Update every 25 records, not every record.
                progress.completedUnitCount = Int64(processed)
            }
            return processed
        }

        return .result(value: processedCount)
    }

    private func process(_ chunk: [Int]) async throws {}
}

When the work is cancelled, the onCancel block I'll cover in the CancellableIntent section takes over.

CancellableIntent: the natural partner of iOS 26.4, not iOS 27

According to Apple's official API metadata, CancellableIntent was introduced across all platforms not with iOS 27, but with iOS 26.4. It resurfaced in WWDC26 Session 345 as the natural complement to LongRunningIntent — a long-running task also needed to become cancellable.

The official definition is: "An interface to support the graceful cancellation of your app intent's task." You use it by wrapping the main body of the work with the withIntentCancellationHandler(operation:onCancel:isolation:) method. The method's onCancel parameter is of type (IntentCancellationReason) -> Void, meaning it hands you the cancellation reason directly:

import AppIntents

struct SyncLibraryIntent: AppIntent, ProgressReportingIntent, CancellableIntent {
    static var title: LocalizedStringResource = "Kütüphaneyi Senkronize Et"

    func perform() async throws -> some IntentResult & ProvidesDialog {
        let batchCount = 8

        return try await withIntentCancellationHandler {
            progress.totalUnitCount = Int64(batchCount)
            for index in 0..<batchCount {
                try await syncBatch(index)
                progress.completedUnitCount = Int64(index + 1)
            }
            return .result(dialog: "\(batchCount) grup senkronize edildi")
        } onCancel: { reason in
            // Clean up based on the reason.
            switch reason {
            case .timeout: cleanupPartialSync(reason: "timeout")
            case .userCancelled: cleanupPartialSync(reason: "user_cancelled")
            default: cleanupPartialSync(reason: "unknown")
            }
        }
    }

    private func syncBatch(_ index: Int) async throws {}
    private func cleanupPartialSync(reason: String) {}
}

Per the WWDC26 session, cancellation can come from three different sources: "whether the person tapped cancel, the system timed out or needed to reclaim resources." You don't need to keep a separate tracker in your own state to tell the reason apart; as the documentation puts it, "If you want to know the reason for cancellation, use the withIntentCancellationHandler(operation:onCancel:isolation:) method that this protocol offers instead." The IntentCancellationReason value passed to the handler carries that information, and you can distinguish between .timeout and .userCancelled as shown above.

Scaling large data sets with EntityCollection

When you use a normal @Parameter array, the system fully resolves every entity before the intent runs — calling the relevant query and filling in all of its properties. With hundreds or thousands of records, that creates a noticeable delay.

EntityCollection is "an array of entity identifiers that you use to improve the efficiency of operations involving large numbers of entities," per Apple's docs. Its signature is struct EntityCollection<Entity> where Entity : AppEntity, arriving with iOS 27.0. Switch the parameter type to this, and the system only carries the entity identifiers, leaving the full resolve to the intent itself:

struct BatchTagPhotosIntent: AppIntent {
    static var title: LocalizedStringResource = "Fotoğrafları Etiketle"

    @Parameter(title: "Fotoğraflar")
    var photos: EntityCollection<PhotoEntity>

    func perform() async throws -> some IntentResult {
        // photos here is a list of identifiers that aren't fully resolved yet;
        // you resolve only the subset you actually need yourself.
        for identifier in photos.identifiers {
            try await tagPhoto(id: identifier, tag: "iOS27")
        }
        return .result()
    }
}

In the WWDC26 session, Apple's team showed this with a Shortcut demo that finds and tags 1,000 photos, describing the result with EntityCollection as "almost instant"; no exact millisecond or percentage figure was shared.

SyncableEntity and cross-device Siri conversations

As Apple defines it, SyncableEntity is "an interface that indicates your entity has an identifier that's consistent across devices." Its signature is protocol SyncableEntity : AppEntity, arriving with iOS 27.0. Its purpose is clear: "Siri uses this capability to transfer a conversation from one device to another."

The problem: if your entity ID is generated per-device (say, a local database row identifier), the same photo gets a different ID on iPhone and iPad. When Siri wants to continue on one device a conversation that started on another, it can't resolve that ID, and the conversation breaks. If the identifier is already consistent across devices — say, a server-issued UUID — you can add the protocol, as the docs put it, "without any additional changes." If you keep the local and stable identifiers separate, make the entity's id property type SyncableEntityIdentifier:

import AppIntents

struct PhotoEntity: AppEntity, SyncableEntity {
    // The local ID (CoreData row identifier) and the stable ID (CloudKit
    // record name) are matched into a single identifier.
    var id: SyncableEntityIdentifier<String, String>
    var title: String

    init(localID: String, stableID: String, title: String) {
        self.id = SyncableEntityIdentifier(local: localID, stable: stableID)
        self.title = title
    }

    static var typeDisplayRepresentation: TypeDisplayRepresentation = "Fotoğraf"
    static var defaultQuery = PhotoQuery()

    var displayRepresentation: DisplayRepresentation {
        DisplayRepresentation(title: "\(title)")
    }
}

struct PhotoQuery: EntityQuery {
    func entities(
        for ids: [SyncableEntityIdentifier<String, String>]
    ) async throws -> [PhotoEntity] { [] }
}

Contextual suggestions with RelevantEntities

The framing of RelevantEntities isn't the same width across the two primary sources, so use it knowing that. The session's definition is broad: "With RelevantEntities, you can suggest entities to the system and provide context about when and why they're relevant." The official doc's summary is narrower: "a type you use to donate your app's songs, albums, artists, and other media items to play during workouts." As of the beta, the only documented context generator on AppEntityContext is audio(_:), meaning you tag your donation with an AudioContext; the session's example ties running playlists to a workout context:

import AppIntents

func donateRunningPlaylists(
    dailyRun: PlaylistEntity,
    runningMix: PlaylistEntity
) async throws {
    let playlistEntities = [dailyRun, runningMix]
    let workoutContext = AppEntityContext.audio(.workout)

    try await RelevantEntities.shared.updateEntities(
        playlistEntities,
        for: workoutContext
    )

    // Remove specific entries:
    try await RelevantEntities.shared.removeEntities(
        playlistEntities,
        from: workoutContext
    )
    // Or remove all of them:
    try await RelevantEntities.shared.removeAllEntities()
}

If you want to narrow the context, there are the workout(activityType:) and workout(intensityLevel:) type methods; the session's example writes .workout(activityType: .running).

The record persists until you call removeAllEntities(), removeAllEntities(for:), removeEntities(_:), or removeEntities(_:from:). For a non-media "contextual suggestion" scenario, the distinction the session suggests is this: use Spotlight for making content searchable, interaction donation for the system learning usage patterns, and RelevantEntities for telling the system which content is relevant in specific situations — these are covered in more detail in the FAQ section below.

ExecutionTargets: which operation runs in which process

When intents live in a package shared by the app and its extensions, the system decides which process runs them using heuristic rules — and that isn't always the right process. Apple's team defines it in the session as: "ExecutionTargets lets you tell the system exactly which process should run your intent." You can choose the main app, an App Intents extension, a WidgetKit extension, or any combination — for example, keeping a data-writing widget button's intent in the main app.

Likewise, @UnionValue also comes from the session: "A Swift enum where each case wraps a different type, letting a single parameter represent one of several options." The macro lets a parameter accept one of several entity types; its use isn't limited to widgets either: "this isn't limited to Widgets — @UnionValue parameters work everywhere your intent does, including the Shortcuts app." As the session puts it, what the macro produces is the type information, case metadata, and picker support the system needs.

@UnionValue
enum MediaSelection {
    case song(SongEntity)
    case album(AlbumEntity)
    case podcast(PodcastEntity)

    static let typeDisplayRepresentation: TypeDisplayRepresentation = "Medya"
    static let caseDisplayRepresentations: [Cases: DisplayRepresentation] = [
        .song: "Şarkı",
        .album: "Albüm",
        .podcast: "Podcast"
    ]
}

struct PlayMediaIntent: AppIntent {
    @Parameter(title: "Medya")
    var selection: MediaSelection

    func perform() async throws -> some IntentResult {
        switch selection {
        case .song(let song): try await play(song)
        case .album(let album): try await play(album)
        case .podcast(let podcast): try await play(podcast)
        }
        return .result()
    }
}

The order to follow when migrating existing AppIntents to iOS 27

The order below is a practical implementation sequence I derived from the API contracts above:

Measure the duration first. If your perform() body regularly exceeds 30 seconds, it's a LongRunningIntent candidate; if it doesn't, you don't need to change anything. Measure on a real device with real data volume — simulator timings can be misleading.
Wrap it in performBackgroundTask. Move it into this closure without changing your existing logic, and fill in the progress fields. Testing this step on its own makes it easier to isolate errors that show up in the next step when you add CancellableIntent.
Add CancellableIntent and write a real onCancel. Don't leave it empty — whether your app stays consistent when the user stops the task depends on this block. Decide here whether you'll roll back partially processed records or leave them as they are.
Review your array parameters. Any @Parameter array carrying more than a few dozen records is an EntityCollection candidate; first clarify whether your intent needs the entity's full property set or just its identifier.
Add SyncableEntity to entities used across devices, especially in scenarios where Siri conversations start on one device and finish on another. If your local ID is already stable (say, a server-assigned UUID), you may not need any additional mapping; you only need a SyncableEntityIdentifier mapping if you have device-specific IDs.
Evaluate RelevantEntities within its documented context. If you're after a general "suggested content" experience, also put Spotlight indexing and the IntentDonationManager donation flow on the table.

Table: Which API solves which problem

API	Problem it solves	iOS version
LongRunningIntent	30-second background run-time limit	iOS 27.0
CancellableIntent	Graceful cancellation and cleanup	iOS 26.4
EntityCollection	Full-resolve cost on large parameter arrays	iOS 27.0
SyncableEntity	Unstable entity ID across devices	iOS 27.0
RelevantEntities	Context-based content suggestions	iOS 27.0
ExecutionTargets	Which process the intent runs in	iOS 27.0
@UnionValue	Multiple entity types in a single parameter	iOS 27.0

Table: Migration prioritization checklist

Symptom	Recommended API	Priority
Intent frequently hits the 30-second timeout	LongRunningIntent + CancellableIntent	High
Parameter array carries hundreds/thousands of records	EntityCollection	High
Same content gives a different Siri result on different devices	SyncableEntity	Medium
Missing content suggestions in a workout/audio context	RelevantEntities	Medium
Unclear or needlessly heavy process placement for the intent	ExecutionTargets	Low

🏆 GOLDEN TIP: When testing progress reporting, verify Live Activity on a real device, not the simulator

Even if LongRunningIntent's progress updates look visually correct in the simulator, the real timing of the Live Activity, its lock-screen behavior, and the latency of a cancel tap reaching onCancel can only be measured realistically on a physical device. Instead of updating progress.completedUnitCount very frequently inside perform(), update it at meaningful stage boundaries; otherwise the Live Activity redraws needlessly often, showing up to the user as a jittery progress bar.

Checklist

I've put together a practical checklist to go through before you start your iOS 27 App Intents migration. This list summarizes the order in which to evaluate the five APIs covered in the sections above, and the steps most often skipped during migration; you can go through it in order before writing a new intent or migrating an existing one.

Measure perform() duration on a real device, confirm whether it exceeds 30 seconds
Don't break your existing error handling when moving it into the performBackgroundTask closure
Add CancellableIntent and write real cleanup in the onCancel handler, don't leave it empty
Use the reason value that arrives in onCancel, don't track the cause in a separate state
Review array parameters, move anything exceeding a hundred records to EntityCollection
Make the id type of entities used across devices SyncableEntityIdentifier
Tag your RelevantEntities donation with a documented context
Test Live Activity behavior on a real device, not the simulator

FAQ

How do you write an intent that runs longer than 30 seconds on iOS 27?

Conform your intent to LongRunningIntent, which also builds on ProgressReportingIntent. Put your work inside a performBackgroundTask block and update progress at regular intervals; per the docs, if you don't update it regularly, the system may cancel the background extension and end your task early. While it runs, an automatic Live Activity appears with a stop option.

What is SyncableEntity, and why can't Siri find the entity across devices?

By default, your entity ID might be generated per device (say, a local database row identifier); the same content gets a different ID on iPhone and iPad. When Siri tries to continue on another device a conversation that started on one, it can't resolve that ID. Add SyncableEntity and provide a stable identifier (server-assigned, or a CloudKit record ID) — making the id property's type SyncableEntityIdentifier if you keep local and stable identifiers separate — and Siri recognizes the entity the same way on every device.

How do you process thousands of records quickly with EntityCollection?

With a normal array parameter, the system fully resolves every entity before the intent runs; with thousands of records this creates a serious delay. Switch the type to EntityCollection and the system only passes identifiers, skipping the full resolve. In Apple's own demo with 1,000 photos, this produced an "almost instant" result; no exact millisecond figure was shared.

How do I make my app visible in iOS 27 Siri?

The distinction the session draws points to three complementary paths. First, indexing your content in Spotlight — that's how Siri finds and surfaces your content. Second, donating user actions with IntentDonationManager; the system learns patterns and suggests similar actions. Third, for content that's never been searched or played, giving the "this content is relevant in this situation" hint with RelevantEntities.

Is using CancellableIntent mandatory, or is LongRunningIntent alone enough?

Not mandatory, but strongly recommended. LongRunningIntent only extends run time; without CancellableIntent, your app gets no chance to clean up when the user stops the work, and can end up half-finished. In the WWDC26 session, the two protocols are presented as a natural pair.

Can I build a general "suggested content" list with RelevantEntities?

The two sources speak at different widths, so be careful. The session describes the API broadly ("suggest entities to the system and provide context about when and why they're relevant"), while the official doc's summary talks about media content like songs, albums, artists, playlists, and podcasts. For a general, non-media suggestion experience, factor in Spotlight indexing and IntentDonationManager donation too.

Update (September 2026)

This guide was written during the beta period. Apple released iOS 27.0 (24A437) and Xcode 27 (27A266a) on September 14, 2026; the APIs above are no longer in beta, they're in general availability. As of September 21, 2026, iOS 27.2 beta 2 (24B5089g) is in distribution.

Conclusion

iOS 27's App Intents update isn't a single big feature, it's a set of five complementary APIs: LongRunningIntent and CancellableIntent make long-running work reliable, EntityCollection solves scale, SyncableEntity provides cross-device consistency, and RelevantEntities handles context-based content suggestions. If you have an existing App Intents integration, it's enough to first identify your duration and scale issues and then follow the migration order above.

If you're not yet familiar with the core App Intents concepts, start with App Intents and Shortcuts integration. To see the Live Activity mechanism in depth, interactive widgets and Live Activity will be useful. If you're curious about Siri's conversation-based side, you can check out voice integration with SiriKit. To see what's broken on the SwiftUI side of iOS 27, you can read State macro and ContentBuilder breaks on iOS 27.

Sources

WWDC26 Session 345 — Discover new capabilities in the App Intents framework — the official introduction of LongRunningIntent, CancellableIntent, EntityCollection, SyncableEntity, RelevantEntities, ExecutionTargets, and @UnionValue.
LongRunningIntent — Apple Developer Documentation — the official definition of the protocol that extends the 30-second background run-time limit.
CancellableIntent — Apple Developer Documentation — graceful cancellation support and using withIntentCancellationHandler(operation:onCancel:isolation:).
EntityCollection — Apple Developer Documentation — the type that reduces the full-resolve cost for large entity sets.
SyncableEntity — Apple Developer Documentation — the cross-device stable entity identifier interface and the SyncableEntityIdentifier example.
RelevantEntities — Apple Developer Documentation — contextual suggestion donation and the updateEntities(_:for:) API.
ProgressReportingIntent — Apple Developer Documentation — the progress-reporting infrastructure that's existed since iOS 17.
Releases — Apple Developer — release dates for iOS 27.0 (24A437), Xcode 27 (27A266a), and iOS 27.2 beta 2 (24B5089g).

Originally published at muhittincamdali.com.

Swift 6 Strict Concurrency: Production Migration Playbook

Muhittin Çamdalı — Mon, 26 Oct 2026 08:09:28 +0000

Swift 6 Strict Concurrency: Production Migration Playbook

Swift 6.0's strict concurrency looks, at first glance, like an opt-in compile flag. But in reality? It's a serious refactor mandate touching every one of your classes, singletons, delegate patterns, and dependency-injection architecture.

This article walks through the 12 common pitfalls you are likely to hit when moving a large production iOS codebase to strict concurrency mode, their fixes, and the correct actor migration order. Spoiler: @MainActor is not the cure for everything.

Pro Tip: Before starting the migration, don't begin with SWIFT_STRICT_CONCURRENCY = complete — start with targeted. Targeted mode only checks Sendable; complete mode also enforces actor isolation. Starting targeted cuts your first-pass error count in half.

1. The Three Levels of Strict Concurrency Mode

Swift 6 strict concurrency is controlled by the SWIFT_STRICT_CONCURRENCY build setting, and it has three levels:

# Minimal — Swift 5.x default behavior
SWIFT_STRICT_CONCURRENCY = minimal

# Targeted — only Sendable explicit marked types check
SWIFT_STRICT_CONCURRENCY = targeted

# Complete — full Swift 6 strict concurrency
SWIFT_STRICT_CONCURRENCY = complete

Practical migration strategy:

Weeks 1-2: Move the whole project from minimal to targeted. Fix Sendable warnings.
Weeks 3-4: Turn on complete mode module by module. The UI layer goes last.
Week 5: Full project on complete. Swift 6 language mode active.

Migrating small modules first (Networking, Persistence) reduces production risk — changes that leak into the UI layer are usually the most expensive.

2. Sendable: The End of Invisible Leaks

A large share of the migration work comes down to Sendable conformance. A type being Sendable means it's safe to share across multiple threads.

// ❌ Strict mode error: User isn't Sendable
class User {
    var name: String
    var preferences: [String: Any]  // [String: Any] isn't Sendable!
}

// ✅ Solution: struct + typed properties
struct User: Sendable {
    let id: UUID
    let name: String
    let preferences: UserPreferences  // Sendable Codable struct
}

Common Sendable pitfalls:

[String: Any] — Any isn't Sendable; use a typed dictionary
URL — Sendable ✓, URLRequest Sendable ✓
Date — Sendable ✓ (Swift 5.5+)
UIImage — not Sendable (reference type, mutable)
NSData — not Sendable; Data is Sendable ✓
Closure types — require the @Sendable annotation

Pro Tip: Don't try to make legacy Objective-C types (NSObject subclasses) Sendable — they're reference types and mutable. Wrap them in a pure-Swift struct instead.

3. Actor Migration Order: The Right Way

Actors are the gold standard for concurrent state in Swift 6. But migrating them in the wrong order means walking into a maze of rework. Recommended order:

Stateless services (URLSession wrapper, JSON decoder) — not an actor, use struct or enum with static methods
Stateful services (cache, session manager) — make them an actor
DI container / service locator — global state, actor or @MainActor class
ViewModels — @MainActor (they have a UI dependency)
Views — SwiftUI is already MainActor-isolated

// Stateful cache → actor (Correct)
actor ImageCache {
    private var cache: [URL: UIImage] = [:]

    func image(for url: URL) -> UIImage? {
        cache[url]
    }

    func setImage(_ image: UIImage, for url: URL) {
        cache[url] = image
    }
}

// Usage: await required
let image = await imageCache.image(for: url)

Pitfall: don't try to preserve your old synchronous APIs when converting to actor. Every public method becomes async. If call sites are too scattered, use a transition wrapper:

@MainActor
final class ImageCacheBridge {
    private let cache: ImageCache

    nonisolated func imageSync(for url: URL) -> UIImage? {
        // Sync fallback for legacy paths (deprecated)
        return MainActor.assumeIsolated {
            self.legacyCacheStorage[url]
        }
    }
}

[[demo:actor-race-sim]]

4. `@MainActor` Pitfalls

@MainActor is the most powerful tool for UIKit/SwiftUI interop. But misuse hurts performance badly.

Pitfall 1: Marking the entire class @MainActor

// ❌ Wrong — JSON parsing blocks the main thread
@MainActor
final class APIClient {
    func fetchUsers() async throws -> [User] {
        let data = try await URLSession.shared.data(from: usersURL).0
        return try JSONDecoder().decode([User].self, from: data)  // 200ms main thread block!
    }
}

// ✅ Correct — only UI-bound method @MainActor
final class APIClient {
    nonisolated func fetchUsers() async throws -> [User] {
        let data = try await URLSession.shared.data(from: usersURL).0
        return try JSONDecoder().decode([User].self, from: data)
    }

    @MainActor
    func updateUI(with users: [User]) {
        // UI update logic
    }
}

Pitfall 2: Incorrectly capturing values in @MainActor closures

Task { @MainActor in
    // This whole block runs on the main thread — don't do heavy work here!
    let processed = self.heavyProcessing()  // main blocking!
    self.updateView(with: processed)
}

// ✅ Correct — heavy work in background, only UI update on main
Task {
    let processed = await self.heavyProcessing()  // arbitrary executor
    await MainActor.run {
        self.updateView(with: processed)
    }
}

Pitfall 3: MainActor.assumeIsolated is for synchronous compatibility, but misuse causes a runtime crash. Only use it where you can guarantee the code is already running on the main thread.

5. Async/Await and Existing Callback Patterns

A large, older codebase can easily have hundreds of closure-based APIs. Migrating all of them to async/await at once isn't feasible.

Bridge pattern:

// Old callback API
func fetchData(completion: @escaping (Result<Data, Error>) -> Void) {
    // legacy code
}

// Async wrapper
func fetchData() async throws -> Data {
    try await withCheckedThrowingContinuation { continuation in
        fetchData { result in
            continuation.resume(with: result)
        }
    }
}

Watch out — withCheckedThrowingContinuation pitfalls:

The continuation is one-shot — resuming it twice by mistake crashes
If you store the closure and never resume it, the async caller hangs forever
Cancellation handling must be explicit — use withTaskCancellationHandler

In production, use @CheckedContinuation to catch continuation leaks (Swift 6 default, has a debug check).

6. Does the Singleton Pattern Survive Strict Concurrency?

You're told singletons are an anti-pattern, but in a codebase with 200K LOC and 8 years of history, they exist and aren't going anywhere. How do they survive strict concurrency?

// ❌ Strict mode error
class AnalyticsTracker {
    static let shared = AnalyticsTracker()  // mutable global state warning
    var sessionID: String = UUID().uuidString
}

// ✅ Solution 1: actor
actor AnalyticsTracker {
    static let shared = AnalyticsTracker()
    var sessionID: String = UUID().uuidString

    func setSession(_ id: String) {
        sessionID = id
    }
}

// ✅ Solution 2: immutable
final class AnalyticsTracker: Sendable {
    static let shared = AnalyticsTracker()
    let sessionID = UUID().uuidString  // immutable, Sendable safe
    private init() {}
}

Decision matrix:

Internal state gets mutated → actor
Pure read-only → Sendable final class
UI-bound singleton → @MainActor final class

7. Delegate Pattern → AsyncSequence Migration

Most Apple frameworks are delegate-based. Under strict concurrency, delegate methods need Sendable conformance.

// Old pattern
class LocationTracker: NSObject, CLLocationManagerDelegate {
    func locationManager(_ manager: CLLocationManager, didUpdateLocations locations: [CLLocation]) {
        // delegate callback
    }
}

// Modern pattern — AsyncSequence
class LocationTracker {
    var locations: AsyncStream<CLLocation> {
        AsyncStream { continuation in
            let bridge = LocationBridge { location in
                continuation.yield(location)
            }
            // CLLocationManager setup
        }
    }
}

// Usage — clean
for await location in tracker.locations {
    await viewModel.updateLocation(location)
}

This pattern works the same way for MapKit, BLE, Camera, and Audio — wrap the old delegates in an AsyncStream.

8. Test Mocking + Sendable

Test mocks need to be Sendable, otherwise tests fail under the concurrent runner.

// Test double — Sendable conform
final class MockUserService: UserServicing, Sendable {
    let stubUsers: [User]

    init(users: [User] = []) {
        self.stubUsers = users
    }

    func fetchUsers() async throws -> [User] {
        stubUsers
    }
}

Pro Tip: XCTest's default test parallelization does a Sendable check. If a test class holds state, mark it @MainActor or move that state into an actor.

9. Production Profiling: The Performance Trade-off

Strict concurrency isn't free. Actor hops add a small cost to every async call. These are the metrics to compare in your own app before and after the migration:

Metric	Why it matters	How to measure
Launch time	Actor hops added to the main thread can delay the first screen	Instruments App Launch template + MetricKit
Memory baseline	Extra tasks and actor objects can raise the memory floor	Xcode Memory Report + MetricKit
CPU under load	Frequent actor hops can raise CPU share in busy flows	Instruments Time Profiler
Build time	Complete mode makes type checking heavier and builds slower	Xcode Build Timeline

Build time is usually the most noticeable increase. Fix: incremental build caching and modularization.

Runtime overhead stays negligible for most mobile apps; still, verify hot paths with Time Profiler.

On the crash side, the expected gain is that data races closed at compile time no longer surface as runtime crashes; measure the effect by comparing crash analytics before and after the migration.

10. Migration Checklist

A recommended sequential checklist for migrating a production app:

[ ] Phase 0: Project on SWIFT_STRICT_CONCURRENCY = targeted, clean build
[ ] Phase 1: Migrate the networking layer, Sendable conformance
[ ] Phase 2: Persistence layer (Core Data, SwiftData) actor migration
[ ] Phase 3: Service container (DI) as actor or @MainActor
[ ] Phase 4: Mark ViewModels @MainActor
[ ] Phase 5: Mark UIKit ViewControllers @MainActor (SwiftUI views already are)
[ ] Phase 6: Turn on SWIFT_STRICT_CONCURRENCY = complete
[ ] Phase 7: Swift 6 language mode (SWIFT_VERSION = 6)
[ ] Phase 8: Enforce strict mode in the CI/CD pipeline
[ ] Phase 9: Two weeks of crash-analytics observation
[ ] Phase 10: Publish the performance baseline

Pro Tip: Don't do the migration on a feature branch — go gradual on main. On a large codebase the migration can take weeks or even months, so conflicts on a long-lived branch are unavoidable. Merging module-by-module into main is far more sustainable.

Conclusion

Strict concurrency is the delivery on Swift's 8-year-old safety promise. The ability to catch data races at compile time is valuable because it closes this class of runtime crashes at the source. But the migration isn't cheap — on a large codebase, budget for effort that can stretch over months, noticeably longer build times, and a small runtime overhead.

The pragmatic call: for new projects, Swift 6 + complete strict concurrency by default. For existing projects, a targeted → complete transition on a phased, module-by-module plan. @MainActor isn't the cure for everything; used correctly, it means keeping heavy work off the main thread with nonisolated.

Related resources:

Originally published at muhittincamdali.com.

Swift 6.3 Migration: Actor Isolation Warnings and Escape Hatches

Muhittin Çamdalı — Mon, 26 Oct 2026 05:04:31 +0000

Don't be surprised if a project that compiled cleanly on Swift 6.2 starts throwing actor isolation warnings after you move to Swift 6.3 without changing a line — it's not a coincidence. Swift 6.3 introduced no new language rule or default for actor isolation; even so, some patterns silent on 6.2 now warn on 6.3 — and in the documented case below, the root isn't a new rule at all but the conservative behavior of region isolation analysis. This isn't a generic "what is strict concurrency" explainer; it shows, directly, which code patterns broke in the 6.2 → 6.3 delta, with real compiler messages and real escape hatches.

💡 Pro Tip: Whether a piece of code is isolated or nonisolated is part of its signature — changing it is almost always a source-breaking change, and that's exactly where you get hit hardest during a version upgrade.

Today's reality: 6.3.3 is shipped, 6.4 is on the way

Swift 6.3 was officially released on March 24, 2026, signed by Holly Borla and Joe Heck. The headline items weren't about concurrency — more flexible C interop, cross-platform build tooling, embedded-environment enhancements, and an official Android SDK. So the official announcement doesn't even mention concurrency; yet the documented warning is real — you'll see why below, in the conservative rule of region isolation analysis.

The release chain today (early September 2026): after 6.3 came the 6.3.1 and 6.3.2 patches, then 6.3.3 on June 30, 2026 — still the current stable tag on swift.org's install page. Meanwhile Swift 6.4 prep continues: Xcode 27 was still in beta at the end of August 2026 (beta 6, August 24, 2026), so 6.4 isn't an officially released version yet. swift.org's August 20, 2026 post "Embedded Swift Improvements Coming in Swift 6.4" even says "coming" right in the title — 6.4 is still a version tried via development snapshots.
Point-Free's post from their Xcode 27 beta days is a live example: the team had to explicitly mark something @MainActor that should already have been so, because of an isolation-checking regression in Swift 6.4, then quickly merged the fix and shipped a release.

Summary of 6.2 → 6.3 language changes

To understand Swift 6.3's tightening of actor isolation, you first need what changed in 6.2 — half of the configuration that triggers the warning, the module's default-isolation setting, arrived in 6.2 via SE-0466.

SE-0466 — Module-wide default actor isolation. This proposal reached "Implemented" status in Swift 6.2 and added a compiler setting that lets @MainActor inference become the default within a module. The goal was to reduce false-positive data-race errors in single-threaded code — in the proposal's own words: "The easiest and best way to model single-threaded code is with a global actor. Everything on a global actor runs sequentially."

SE-0461 — nonisolated(nonsending) default. Also "Implemented" in 6.2, this proposal changed the behavior of nonisolated async functions: such functions now run on the caller's actor by default instead of hopping to a separate executor. The NonisolatedNonsendingByDefault upcoming-feature flag turns this behavior on.

Together these two changes make 6.2's philosophy clear: the compiler now runs on "sequential by default, parallel when needed" logic. 6.3 announced no new concurrency default; even so, some patterns silent on 6.2 now produce new isolation warnings.

Documented case: the `@Sendable` × `@escaping` isolation warning

A thread opened by Itai Ferber on the Swift Forums is the most concrete documented example. Ferber's description is precise, in his own words: "This only reproduces on Swift 6.3 in a project with nonisolated default isolation and concurrency checking set to Complete; earlier Swift versions, default MainActor isolation, or minimal/targeted concurrency checking don't produce this warning."

This alone gives a practical hint: if your project uses the -default-isolation MainActor flag (i.e., you've turned on SE-0466's MainActor-default at the module level), you won't see this specific warning. The producing configuration: module default isolation still nonisolated, target compiled with SWIFT_STRICT_CONCURRENCY=complete.

// Reproducer from Ferber's forum thread: silent on 6.2, warns on 6.3
class External {
    // System-provided, Obj-C-originated signature (in reality, Timer.scheduledTimer)
    static func ƒ1(_ work: @escaping @Sendable () -> Void) {
        work()
    }
}

@MainActor
final class Internal {
    func ƒ2(_ completion: @escaping () -> Void) {
        completion()
    }

    func ƒ3() {
        Task { @MainActor in
            var complete = false
            External.ƒ1 {
                MainActor.assumeIsolated {
                    self.ƒ2 {
                        MainActor.assumeIsolated {
                            // ⚠️ Sending 'complete' risks causing data races
                            complete = true
                        }
                    }
                }
            }

            print(complete)
        }
    }
}

Ferber's actual compiler output reads: "Sending 'complete' risks causing data races; this is an error in the Swift 6 language mode ... Task-isolated 'complete' is captured by a main actor-isolated closure." Notice: the warning isn't about the closure itself, but the capture of the var complete variable defined inside the Task { @MainActor in } body.

Two fixes are documented: removing @Sendable from External.ƒ1(), or @escaping from Internal.ƒ2(). In Ferber's words: "Removing @Sendable from External.ƒ1() or @escaping from Internal.ƒ2() resolves the warning." Why: because complete passes through a nonisolated context, it must be implicitly sent to MainActor, and sending semantics require statically verifying the value can no longer be used from the source context — impossible in nonisolated contexts. Ferber accepts the diagnosis: "warning about such a mutable var capture seems reasonable."

Configuration	6.2 behavior	6.3 behavior
`nonisolated` default + Complete checking	Compiles silently	Warning on Sendable+escaping closure
`-default-isolation MainActor` (SE-0466 on)	Compiles silently	Compiles silently (no warning)
Minimal/targeted checking	Compiles silently	Compiles silently
`@Sendable` OR `@escaping` alone	No issue	No issue

Takeaway: check -default-isolation — but as diagnosis, not a fix. Flipping to the MainActor-default makes the warning vanish; that doesn't prove the code race-free. As jamieQ put it, "this is a limitation of how the region isolation analysis implementation applies its conservative rules" — if the code really is safe, a deliberate escape hatch (nonisolated(unsafe)) is reasonable. An alternative from the same thread: instead of the implicit box the compiler generates for the closure capture, put the value in your own reference type with matching isolation — a wrapper like @MainActor final class Workaround<T>.

Escape hatches: `nonisolated(unsafe)` and `@preconcurrency`

nonisolated(unsafe) is one of the most commonly reached-for escape hatches in Swift 6 migrations — but sprinkling it everywhere can hide real data races instead of speeding up the migration. A real migration account on the Swift Forums shows the distinction: "A few legacy/spaghetti code issues came up but were resolvable with nonisolated(unsafe)." The same post notes third-party libraries: "Dealing with third-party libraries was pretty easy — it was usually enough to just add @preconcurrency to the import or protocol and move on." Neither is specific to 6.3 — general Swift 6 migration practice — but both remain your first line of defense moving to 6.3.

import Foundation

// Quickly silencing a legacy singleton (use with care — can hide a real data race)
final class LegacyCache {
    nonisolated(unsafe) static var shared = LegacyCache()
    private var storage: [String: Data] = [:]
}

// A representative third-party protocol not yet Sendable-conformant
protocol RequestDelegate {
    func didFinish(_ payload: Data)
}

@MainActor
final class APIClient: @preconcurrency RequestDelegate {
    // @preconcurrency defers the conformance's isolation check to runtime
    func didFinish(_ payload: Data) {
        print(payload.count)
    }
}

Protocol conformance isolation is a separate layer: SE-0470 "Global-actor isolated conformances" — status "Implemented (Swift 6.2)" — pins down the rules for a type conforming to a protocol in a global-actor-isolated way (an @MainActor class conforming to a nonisolated protocol, say), turned on via the InferIsolatedConformances upcoming-feature flag. Effect: an @MainActor-marked type conforming to a protocol that doesn't require isolation may now need explicit annotation.

The root of the same case: region isolation analysis

The root of the warning has less to do with which actor a closure "resumes" on, and more with how the compiler classifies the captured variable: the Task-isolated complete is considered sent the moment it's captured by an @MainActor-isolated closure.

John McCall from the Swift team describes this in the same thread: "The problem is simply that Swift treats a capture in a closure with different isolation as a send, when what we actually need to do is reason about the isolation of the functions where the captured variable is used." The distinction matters: this only shows up with indirect captures — a variable captured by the outer closure only because it's used in a more deeply nested one. Point-Free's note on the Xcode 27/Swift 6.4 beta process shows that, in a library adopting NonisolatedNonsendingByDefault, 6.4 keeps tightening checking: "Swift 6.4 seems to have started catching more issues in async code related to this setting" — meaning closure/async isolation checking keeps tightening from 6.3 toward 6.4, a gradual trend rather than a one-time jump.

import Foundation

// Counter-example: isolation chain is NOT broken here — shows what the
// indirect-capture pattern above does NOT look like
actor DownloadManager {
    func fetch(completion: @escaping @Sendable (Result<Data, Error>) -> Void) {
        Task {
            let data = await performFetch()
            // Task inherits the actor's isolation; completion is @Sendable,
            // so there's no mutable capture being sent across a boundary
            completion(.success(data))
        }
    }

    private func performFetch() async -> Data { Data() }
}

The first question to ask in practice when you hit warnings like this: "Which actor should this closure live on, and is its isolation determined explicitly or by inference?"

Gradual migration without turning warnings into errors

The most common mistake moving to 6.3 is pulling the entire target into Swift 6 language mode in one shot. swift.org's migration guide states the rule explicitly: "In targets that adopt the Swift 6 language mode, complete checking is unconditionally on and requires no setting change." So there's no in-between; the line from a Swift Forums account — "First I switched the language version in Xcode to 6 and set concurrency checking to minimal" — actually contradicts this rule. The gradual path is the reverse: keep the target in Swift 5 mode, raise "Strict Concurrency Checking" in Xcode from minimal → targeted → complete, clean up warnings, then switch the language mode to 6.

// swift-tools-version: 6.0
import PackageDescription

let package = Package(
    name: "MyPackage",
    targets: [
        // Step 1: v5 language mode + complete checking (warnings only)
        .target(
            name: "LegacyModule",
            swiftSettings: [
                .swiftLanguageMode(.v5),
                .enableUpcomingFeature("StrictConcurrency")
            ]
        ),
        // Step 2: swiftSettings removed, target falls back to default v6 language mode
        .target(name: "MigratedModule")
    ]
)

Step two: walk back carelessly sprinkled @MainActor annotations. The same forum post admits: "Looking back later, I realized I could remove some of the mainactor annotations I'd added carelessly." Reaching for @MainActor everywhere as a "silence the error" reflex creates debt to clean up later — better to understand the actual data-race point the compiler flags and fix it there.

Step three: when a team hits a compiler regression or an overly conservative diagnosis, open an issue and apply a temporary workaround without waiting for a language-team fix. Point-Free sums it up: "We've filed issues about these problems, but that doesn't help our users. So we've applied workarounds in the meantime." If you get stuck on a regression, add the annotation and keep moving — track the issue separately.

Managing version conflicts in SPM packages

A version upgrade affects not just your own code but the SPM packages you depend on — and their maintainers may have hit the same regressions first. Point-Free's experience with ComposableArchitecture and StructuredQueries is a good example. For StructuredQueries: "Swift 6.4 seems to have introduced a small type-checking regression that broke compilation of @Table macro code. The fix was simple ... and we shipped a release within 2 days." A similar quick-fix cycle played out for ComposableArchitecture too (the @MainActor example above).

This shows a concrete order to follow for dependency management when moving to 6.3 (or later 6.4):

Check package versions first: look in the changelogs of your critical packages (ones like ComposableArchitecture, StructuredQueries) for a patch note mentioning "Swift 6.3" or "isolation."
Don't upgrade the target without updating the package: before changing your compiler version, run swift package update to pull dependencies to their latest patch — maintainers have usually hit the regression before you.
If a version is locked, track the issue: if your Package.resolved has locked a version predating 6.3, search the package's GitHub issues for "6.3" or "isolation."
Temporary workaround in your own fork: if a critical package hasn't shipped a fix yet — with a reflex similar to what Point-Free did on the maintainer side — open the issue and add a temporary nonisolated(unsafe) or an explicit @MainActor in your own integration layer while you wait for the package's official fix, rather than forking the package itself.

These two examples confirm something else: isolation regressions during upgrades aren't specific to your codebase — popular production libraries hit the same friction. Knowing you're not alone helps morale during the migration.

What to expect in Swift 6.4

No official GA date for Swift 6.4 has been announced — Xcode 27 is still in beta as of early September 2026. But swift.org's August 20, 2026 post, signed by Doug Gregor, documents concrete 6.4 Embedded Swift improvements: "Embedded Swift previously only supported existential (any) types with the AnyObject constraint ... Now all any types, including Any itself, are usable in Embedded Swift." The same post expands untyped-throws support: "Untyped throws is equivalent to throwing a value of type any Error. With the generalization of any types, Embedded Swift now fully supports untyped throws." Metatypes get their own section too: "Swift 6.4 brings complete support for metatypes in Embedded Swift."

These changes don't target actor isolation directly, but matter for teams using Swift in embedded systems (microcontrollers, WebAssembly) — and Point-Free's experience shows 6.4's concurrency checking keeps up 6.3's tightening trend, sometimes surfacing new regressions. Advice: don't jump to the 6.4 beta before finishing your 6.3 migration — tracking the two versions' isolation-behavior differences separately makes it easier to tell which warning came from where.

If your team is following the Xcode 27 betas, watching the monthly digests on the swift.org/blog page (like the September 4, 2026 "What's new in Swift: August 2026 Edition") is the most reliable way not to miss the moment 6.4 approaches stable — the official announcement usually lands in sync with Xcode's own GA.

🏆 GOLDEN TIP: The fastest way to isolate a warning

When you hit a new isolation warning, ask this first: at which checking level (minimal/targeted/complete) and under which default-isolation setting (nonisolated/MainActor) does it appear? As in Itai Ferber's forum finding, the same code can produce four different outcomes under four different configurations. Temporarily flipping your target's SWIFT_STRICT_CONCURRENCY and -default-isolation flags and recompiling the same file lets you tell, within a few minutes, whether the warning is a real data race or a configuration-dependent compiler behavior. But remember: this is a diagnostic tool, not a fix — a configuration where the warning disappears doesn't prove the code is safe.

Checklist

We put together a short checklist you can keep on hand to figure out whether your project is really ready to move to Swift 6.3. Check off the items below in order; each one corresponds to a real warning case or escape hatch mentioned in this post.

Note your target's default-isolation setting (nonisolated or MainActor) and its concurrency checking level (minimal/targeted/complete)
List every function that uses a Sendable + escaping closure combination
Flag every line using nonisolated(unsafe) and re-review whether it's genuinely safe
Scan third-party imports for places that need @preconcurrency added
Check the Swift 6.3 compatibility notes for your critical dependencies (especially actor/concurrency-heavy packages)
Staying in Swift 5 language mode, raise the checking level from minimal to targeted to complete, and switch the language mode to 6 last
Re-review any @MainActor annotations added carelessly during migration once the migration is done
Fully finish your 6.3 migration before moving to the Xcode 27 beta — don't mix the isolation behavior of the two versions

FAQ

What code breaks when moving from Swift 6.2 to 6.3?

The most common breaking point is code using @Sendable @escaping closures under the combination of nonisolated module default and Complete concurrency checking. In a case documented on the Swift Forums, this combination compiled silently on 6.2 but starts producing a "risks causing data races" warning on 6.3. The general rule: since a declaration's isolation status (isolated/nonisolated) is part of its API contract, a version upgrade can change how that contract is checked.

Why is actor isolation stricter in Swift 6.3?

The official 6.3 announcement doesn't declare a new concurrency feature; even so, some patterns that compiled silently on 6.2 produce warnings on 6.3. In the documented case, the source isn't a new rule at all, but the conservative behavior of region isolation analysis: a mutable variable captured in a closure with different isolation is treated as "sent."

When will Swift 6.4 be released?

No exact GA date has been officially announced. What's known: Xcode 27 (which includes Swift 6.4) has been in beta since June 2026 and was at beta 6 as of August 24, 2026. swift.org's August 20, 2026 Embedded Swift post also describes 6.4 as still "coming" — as of early September 2026, 6.4 has not been officially released.

When should I use nonisolated vs. @concurrent?

nonisolated(nonsending) is suited for helper functions that are a logical part of the caller's work and don't need to hop to a separate thread — such functions stay on the caller's actor. @concurrent, on the other hand, is for genuinely expensive work that must run in parallel and shouldn't block the caller's actor — it's used to explicitly request the old "always run on a separate executor" behavior. When the NonisolatedNonsendingByDefault flag is on, plain nonisolated async functions stay on the caller's actor by default; you need to explicitly mark any function where you want to keep the old behavior with @concurrent.

Which build settings should I check before moving to 6.3?

Check your target's -default-isolation flag (MainActor or nonisolated) and its SWIFT_STRICT_CONCURRENCY level (minimal/targeted/complete). Per the forum finding in this post, the same code produces different results on 6.3 depending on the combination of these two settings — the documented warning doesn't appear in projects with the MainActor-default turned on.

Should I clean up my existing nonisolated(unsafe) usages before moving to 6.3?

Not mandatory, but recommended. nonisolated(unsafe) should remain a temporary escape hatch; the 6.3 migration is a good opportunity to review whether these annotations are still necessary or are simply leftovers from an old "silence it and move on" reflex.

Conclusion

Migrating to Swift 6.3 is less about learning a new language feature and more about understanding how the compiler now checks the actor isolation defaults introduced by 6.2 (SE-0466, SE-0461). The documented case teaches the lesson on its own: a mutable variable indirectly captured behind a Sendable+escaping signature runs into the conservative rule of region isolation analysis. Protocol conformance isolation (SE-0470) ties back to the same root: isolation is now a checked part of the API contract. If you want to refresh Swift's strict concurrency foundations before this migration, the Swift 6 Strict Concurrency Deep Guide is a good starting point; if you're looking for a step-by-step migration plan, the Swift 6 Strict Concurrency Migration Playbook complements this post.

If you want a deeper look at how actors fundamentally work, check out Swift Concurrency and Actors; for the Task and TaskGroup side of structured concurrency, see Swift Structured Concurrency. For projects using actors in distributed systems, Swift Distributed Actors covers the beyond-the-network isolation scenarios this post doesn't. You can also refresh the background on the general concurrency updates that came with Swift 6.2 at WWDC26 from Swift 6.2 Concurrency Innovations.

One last note: every example in this article was written against 6.3.3 (today's stable release). If you've started trying Swift 6.4 with the Xcode 27 beta, keep in mind that isolation behavior may differ from 6.3 — keeping the two versions' regressions separate in the same migration process makes it easier to tell where each warning is coming from.

Sources

Swift 6.3 Released — official 6.3 announcement, March 24, 2026, summary of language changes
Announcing Swift 6.3.3 — June 30, 2026 patch announcement, current stable release
Embedded Swift Improvements Coming in Swift 6.4 — August 20, 2026, Doug Gregor, official evidence that 6.4 hasn't shipped yet
SE-0466: Control Default Actor Isolation — module-wide default isolation proposal, Implemented in 6.2
SE-0461: Run nonisolated async functions on the caller's actor — the nonisolated(nonsending) proposal, Implemented in 6.2
New Swift 6.3 isolation warnings with Sendable x escaping escape hatch — Itai Ferber, Swift Forums, February 25, 2026, the primary source for this post
My experience (attempting) a migration to swift 6 — Swift Forums, April 3, 2025, a gradual-migration account from the Swift 6.0 era
Xcode 27 Support in the Point-Free Ecosystem — Point-Free, real regression-fix examples from ComposableArchitecture/StructuredQueries
Enable data-race safety checking — swift.org migration guide, language mode and checking level rules
What's new in Swift: August 2026 Edition — swift.org, September 4, 2026, monthly digest

Originally published at muhittincamdali.com.

DEV Community: Muhittin Çamdalı

SwiftUI Document API: ReadableDocument and WritableDocument

Why the new protocols arrived

Migrating FileDocument → ReadableDocument (a side-by-side example)

What the old FileDocument side used to look like

The role of PageSnapshot and DocumentReader

ReferenceFileDocument → WritableDocument

A concrete Writer type

Exporting the same document as PNG too

Incremental and asynchronous writing

Computing the diff with the previous parameter

Progress reporting with Subprogress

What the consuming keyword means

DocumentCreationSource and NewDocumentButton

Adding multiple sources to the scene

iCloud/Files integration pitfalls

Why autosave doesn't trigger without a registered undo action

iOS 26 backward compatibility

What to do with a mixed deployment target

🏆 GOLDEN TIP: Don't make the migration a "big bang"

Checklist

FAQ

What replaces FileDocument now?

What's the difference between ReadableDocument and WritableDocument?

How do I incrementally save a large file in SwiftUI?

How do you define multiple new-document sources in a DocumentGroup?

What happens if I don't register an undo action?

Do I need to change my old FileDocument code right away?

Update (September 2026)

Conclusion

Sources

App Intents on iOS 27: LongRunningIntent and Siri

Why App Intents matters again on iOS 27

Breaking the 30-second wall with LongRunningIntent

Writing progress to Live Activity: using the progress object correctly

CancellableIntent: the natural partner of iOS 26.4, not iOS 27

Scaling large data sets with EntityCollection

SyncableEntity and cross-device Siri conversations

Contextual suggestions with RelevantEntities

ExecutionTargets: which operation runs in which process

The order to follow when migrating existing AppIntents to iOS 27

Table: Which API solves which problem

Table: Migration prioritization checklist

🏆 GOLDEN TIP: When testing progress reporting, verify Live Activity on a real device, not the simulator

Checklist

FAQ

How do you write an intent that runs longer than 30 seconds on iOS 27?

What is SyncableEntity, and why can't Siri find the entity across devices?

How do you process thousands of records quickly with EntityCollection?

How do I make my app visible in iOS 27 Siri?

Is using CancellableIntent mandatory, or is LongRunningIntent alone enough?

Can I build a general "suggested content" list with RelevantEntities?

Update (September 2026)

Conclusion

Sources

Swift 6 Strict Concurrency: Production Migration Playbook

Swift 6 Strict Concurrency: Production Migration Playbook

1. The Three Levels of Strict Concurrency Mode

2. Sendable: The End of Invisible Leaks

3. Actor Migration Order: The Right Way

4. @MainActor Pitfalls

5. Async/Await and Existing Callback Patterns

6. Does the Singleton Pattern Survive Strict Concurrency?

7. Delegate Pattern → AsyncSequence Migration

8. Test Mocking + Sendable

9. Production Profiling: The Performance Trade-off

10. Migration Checklist

Conclusion

Swift 6.3 Migration: Actor Isolation Warnings and Escape Hatches

Today's reality: 6.3.3 is shipped, 6.4 is on the way

Summary of 6.2 → 6.3 language changes

Documented case: the @Sendable × @escaping isolation warning

Escape hatches: nonisolated(unsafe) and @preconcurrency

The root of the same case: region isolation analysis

Gradual migration without turning warnings into errors

Managing version conflicts in SPM packages

What to expect in Swift 6.4

🏆 GOLDEN TIP: The fastest way to isolate a warning

Checklist

FAQ

4. `@MainActor` Pitfalls

Documented case: the `@Sendable` × `@escaping` isolation warning

Escape hatches: `nonisolated(unsafe)` and `@preconcurrency`