Add observation-aware NSModelActor initialization

Author: fatbobman

Docs/NSModelActorGuide.md

@@ -74,6 +74,8 @@ the macro adds:
 - `nonisolated let modelExecutor: NSModelObjectContextExecutor`
 - `nonisolated let modelContainer: NSPersistentContainer`
 - `init(container: NSPersistentContainer)` unless disabled
+- `init(observationDomain: CDEObservationDomain)` with Swift compiler 6.2+ on iOS 17+ /
+  macOS 14+ platform families, unless disabled
 - `NSModelActor` conformance
 
 The generated initializer always uses:
@@ -84,6 +86,38 @@ let context = container.newBackgroundContext()
 
 That is an intentional behavior contract in this package.
 
+The Observation-aware initializer is available when CDE's MainActor Observation runtime is available
+(Swift compiler 6.2+ plus the platform availability below):
+
+```swift
+@MainActor
+@available(iOS 17.0, macOS 14.0, tvOS 17.0, watchOS 10.0, visionOS 1.0, *)
+init(observationDomain: CDEObservationDomain)
+```
+
+It creates and registers the actor's background context through the domain:
+
+```swift
+let container = observationDomain.modelContainer
+let context = container.newBackgroundContext()
+observationDomain.registerChangeProducer(context: context)
+modelExecutor = NSModelObjectContextExecutor(context: context)
+modelContainer = container
+```
+
+Use this initializer when the actor owns background writes and you want direct
+`modelContext.save()` calls to produce property-level Observation metadata. The generated actor keeps
+the domain and producer registration alive for its own context. Inline construction is valid:
+
+```swift
+let writer = ItemStore(observationDomain: CDEObservationDomain(container: container))
+```
+
+Releasing the actor releases its retained domain/registration, and that teardown is safe even if the
+actor's final release happens off the MainActor. If the retained domain is explicitly invalidated
+while the actor lives, the actor remains a valid Core Data actor; its context is no longer a
+registered Observation producer, so normal unregistered-context fallback rules apply.
+
 ## What `@NSMainModelActor` Generates
 
 For a class declaration:
@@ -156,6 +190,23 @@ create a new scheduling layer.
 For production writes, prefer dedicated mutation methods on the actor or class instead of exposing
 raw context access everywhere.
 
+### `saveObservedChanges()`
+
+For actors created with `init(observationDomain:)`, the generated no-argument
+`saveObservedChanges()` saves the actor context through the retained Observation setup:
+
+```swift
+try await saveObservedChanges()
+```
+
+When the actor is not bound to an observation domain, this method falls back to a plain
+`modelContext.save()` and logs a one-time runtime warning that no CDE Observation metadata will be
+produced.
+
+This no-argument overload is generated with the initializer set. When using
+`@NSModelActor(disableGenerateInit: true)`, define your own save wrapper if you need stored-domain
+fallback behavior.
+
 ## Custom Initializers
 
 If you need extra stored properties or a custom context setup, disable initializer generation:
@@ -203,6 +254,36 @@ For `@NSMainModelActor`, that means:
 
 - `modelContainer`
 
+### Custom Observation-aware initializers
+
+When a custom `@NSModelActor` initializer should keep the same Observation producer behavior as the
+generated overload, retain the domain and producer registration alongside the context:
+
+```swift
+@NSModelActor(disableGenerateInit: true)
+actor ItemStore {
+  private let observationDomain: CDEObservationDomain?
+  private let observationProducerRegistration: CDEObservationProducerRegistration?
+
+  init(observationDomain: CDEObservationDomain) {
+    let container = observationDomain.modelContainer
+    let context = container.newBackgroundContext()
+    self.observationDomain = observationDomain
+    observationProducerRegistration = observationDomain.registerChangeProducer(context: context)
+    modelExecutor = NSModelObjectContextExecutor(context: context)
+    modelContainer = container
+  }
+
+  deinit {
+    observationProducerRegistration?.invalidate()
+  }
+}
+```
+
+For custom actors, keep your own save wrapper if you need optional fallback behavior. The existing
+`saveObservedChanges(in:)` remains useful for plain actor contexts that do not retain a producer
+registration.
+
 ## Testing Patterns
 
 ### Use `NSPersistentContainer.makeTest`

Docs/ObservationGuide.md

@@ -15,8 +15,10 @@ invalidation.
 
 ## Availability
 
-MainActor Observation requires Swift Observation platform support:
+MainActor Observation requires Swift compiler support for CDE's Observation runtime plus Swift
+Observation platform support:
 
+- Swift compiler 6.2+
 - iOS 17+
 - macOS 14+
 - tvOS 17+
@@ -93,7 +95,7 @@ saved change for `title`, Swift Observation invalidates that reader.
 Observation consumption is MainActor-bound and centered on `container.viewContext`.
 
 - Read observed model objects from MainActor UI code.
-- Keep `CDEObservationDomain` on MainActor.
+- Create and explicitly invalidate `CDEObservationDomain` on MainActor.
 - Treat background contexts as metadata producers only. They should not publish Observation changes
   directly.
 - If an opt-in model is used without a retained domain for its `viewContext`, reads can still compile,
@@ -126,7 +128,8 @@ Use the strongest producer route that matches the context you own.
 | Source | Public API | Precision | Notes |
 |---|---|---|---|
 | `viewContext` save | `try viewContext.save()` | property-level | A retained domain instruments its own `viewContext`; `NSMainModelActor.saveObservedChanges(in:)` is symmetry sugar. |
-| `@NSModelActor` background save | `try await saveObservedChanges(in: observation)` | property-level | Stages changed keys before save without suspending between staging and commit. |
+| Observation-aware `@NSModelActor` background save | create the actor with `init(observationDomain:)`, then call `try modelContext.save()` or `try await saveObservedChanges()` | property-level after successful save | The generated initializer retains the domain and registration for its actor context. |
+| Plain `@NSModelActor` background save | `try await saveObservedChanges(in: observation)` | property-level | Stages changed keys before save without suspending between staging and commit. |
 | Arbitrary context wrapper | `try await observation.saveObservedChanges(in: context)` | property-level | Preferred when thrown-save cleanup matters; the wrapper rolls back its staged token and the context on failure. |
 | Registered ordinary context | `observation.registerChangeProducer(context:)`, then plain `context.save()` | property-level after successful save | If a direct save throws, call `rollback()`, `reset()`, or invalidate the registration to clear staged notification state. |
 | Convenience background context | `observation.newObservedBackgroundContext()` | property-level after successful save | Equivalent to `container.newBackgroundContext()` plus producer registration. |
@@ -136,7 +139,31 @@ Use the strongest producer route that matches the context you own.
 
 ## Background Actor Save
 
-Prefer `NSModelActor.saveObservedChanges(in:)` for actor-owned background writes:
+When the actor can be created on MainActor from the retained observation domain, prefer the generated
+Observation-aware initializer:
+
+```swift
+@NSModelActor
+actor ItemWriter {
+  func rename(
+    id: NSManagedObjectID,
+    to title: String
+  ) throws {
+    guard let item = self[id, as: Item.self] else { return }
+    item.title = title
+    try modelContext.save()
+  }
+}
+
+let writer = ItemWriter(observationDomain: CDEObservationDomain(container: container))
+```
+
+The generated actor retains the domain and producer registration for its actor context. Inline
+construction is supported: releasing the actor releases its retained domain/registration, and teardown
+is safe even when the actor's final release happens off the MainActor.
+
+For an actor created with the plain `init(container:)`, use `NSModelActor.saveObservedChanges(in:)`
+for actor-owned background writes that need property-level metadata:
 
 ```swift
 @NSModelActor
@@ -153,9 +180,11 @@ actor ItemWriter {
 }
 ```
 
-Calling `modelContext.save()` still saves Core Data correctly, but it bypasses CDE's precise metadata
-staging. The domain can only fall back to object-level invalidation when a later merge supplies object
-IDs.
+Calling `modelContext.save()` from a plain, unregistered actor context still saves Core Data
+correctly, but it bypasses CDE's precise metadata staging. The domain can only fall back to
+object-level invalidation when a later merge supplies object IDs. If that actor uses the generated
+no-argument `saveObservedChanges()` from the plain `init(container:)` path, CDE logs a one-time
+warning and performs the same plain save.
 
 ## Registered Ordinary Contexts
 
@@ -283,7 +312,7 @@ userInfo-key summaries are diagnostic details and may change between releases.
   Precision Across Store Re-merges).
 - Generated setters do not provide immediate unsaved refresh.
 - To-many relationship setters are still not generated; use the generated relationship helper methods.
-- Keep all UI reads and domain lifecycle operations on MainActor.
+- Keep all UI reads and manual domain create/invalidate calls on MainActor.
 
 ## Related Guides
 

Sources/CoreDataEvolution/CoreDataEvolution.docc/CoreDataEvolution.md

@@ -31,9 +31,15 @@ CoreDataEvolution allows you to create actors with custom executors tied to Core
 ### MainActor Observation for Persistent Models
 
 `@PersistentModel(observation: .mainActor)` opts a generated `NSManagedObject` model into Swift
-Observation on iOS 17+ / macOS 14+ platform families. A retained `CDEObservationDomain` activates
-MainActor routing for a container's `viewContext`, so SwiftUI can read generated Core Data accessors
-directly and refresh after saved changes or merges.
+Observation with a Swift 6.2+ compiler on iOS 17+ / macOS 14+ platform families. A retained
+`CDEObservationDomain` activates MainActor routing for a container's `viewContext`, so SwiftUI can
+read generated Core Data accessors directly and refresh after saved changes or merges.
+
+Background actors generated by `@NSModelActor` can also be created with
+`init(observationDomain:)` on those platform families. That initializer creates a registered
+background context and retains the domain setup so direct actor `modelContext.save()` calls can
+publish property-level Observation metadata. Inline domain construction is supported; releasing the
+actor releases its retained domain setup safely.
 
 ## Basic Usage
 
@@ -124,6 +130,7 @@ import CoreDataEvolution
 - Swift 6.0
 
 > Important: The custom executor uses a compatible `UnownedJob` serial-executor path to support the minimum deployment targets.
+> MainActor Observation additionally requires a Swift 6.2+ compiler and iOS 17+ / macOS 14+ platform families.
 
 ## Acknowledgments
 

Sources/CoreDataEvolution/Macros.swift

@@ -92,13 +92,20 @@ public enum RelationshipDeleteRule: String, Sendable, Codable {
 /// - stores an `NSPersistentContainer`
 /// - creates a background `NSManagedObjectContext`
 /// - exposes `modelExecutor`
-/// - optionally synthesizes `init(container:)`
+/// - optionally synthesizes `init(container:)` and the Observation-aware
+///   `init(observationDomain:)` on supported OS versions
+/// - when initializer generation is enabled, synthesizes `saveObservedChanges()` for actors bound
+///   to an observation domain
 ///
 /// Use this when Core Data work should run off the main actor.
 ///
 /// - Parameter disableGenerateInit: When `true`, the macro does not synthesize
-///   `init(container:)` and your type must initialize the generated stored properties itself.
-@attached(member, names: named(modelExecutor), named(modelContainer), named(init))
+///   generated initializers and your type must initialize the generated stored properties itself.
+@attached(
+  member,
+  names: named(modelExecutor), named(modelContainer), named(init), named(saveObservedChanges),
+  named(deinit), named(__cdeObservationDomain), named(__cdeObservationProducerRegistration)
+)
 @attached(extension, conformances: NSModelActor)
 public macro NSModelActor(disableGenerateInit: Bool = false) =
   #externalMacro(module: "CoreDataEvolutionMacros", type: "NSModelActorMacro")
@@ -230,18 +237,32 @@ public macro _CDObserved(
 ///   properties for every to-many relationship using the underlying Objective-C collection count.
 /// - Parameter observation: Optional Observation code generation mode. The default keeps existing
 ///   generated output unchanged.
-@attached(memberAttribute)
-@attached(member, names: arbitrary, named(__cdRuntimeEntitySchema))
-@attached(
-  extension,
-  conformances: PersistentEntity, CDRuntimeSchemaProviding, CDEObservable,
-  CDEObservationFieldMapProviding, CDEObservationInvalidationDispatching
-)
-public macro PersistentModel(
-  generateInit: Bool = false,
-  generateToManyCount: Bool = true,
-  observation: PersistentModelObservationMode = .none
-) = #externalMacro(module: "CoreDataEvolutionMacros", type: "PersistentModelMacro")
+#if compiler(>=6.2)
+  @attached(memberAttribute)
+  @attached(member, names: arbitrary, named(__cdRuntimeEntitySchema))
+  @attached(
+    extension,
+    conformances: PersistentEntity, CDRuntimeSchemaProviding, CDEObservable,
+    CDEObservationFieldMapProviding, CDEObservationInvalidationDispatching
+  )
+  public macro PersistentModel(
+    generateInit: Bool = false,
+    generateToManyCount: Bool = true,
+    observation: PersistentModelObservationMode = .none
+  ) = #externalMacro(module: "CoreDataEvolutionMacros", type: "PersistentModelMacro")
+#else
+  @attached(memberAttribute)
+  @attached(member, names: arbitrary, named(__cdRuntimeEntitySchema))
+  @attached(
+    extension,
+    conformances: PersistentEntity, CDRuntimeSchemaProviding
+  )
+  public macro PersistentModel(
+    generateInit: Bool = false,
+    generateToManyCount: Bool = true,
+    observation: PersistentModelObservationMode = .none
+  ) = #externalMacro(module: "CoreDataEvolutionMacros", type: "PersistentModelMacro")
+#endif
 
 /// Declares metadata for a persisted attribute.
 ///

Sources/CoreDataEvolution/ModelActorSupport.swift

@@ -39,25 +39,57 @@ func withModelContext<T: Sendable>(
   try action(context, container)
 }
 
-@available(iOS 17.0, macOS 14.0, tvOS 17.0, watchOS 10.0, visionOS 1.0, *)
-func collectChangedObservationFieldSets(
-  from objects: Set<NSManagedObject>
-) -> [NSManagedObjectID: CDEObservationFieldSet] {
-  objects.reduce(into: [:]) { result, object in
-    guard object.objectID.isTemporaryID == false else {
-      return
+#if compiler(>=6.2)
+  @available(iOS 17.0, macOS 14.0, tvOS 17.0, watchOS 10.0, visionOS 1.0, *)
+  func collectChangedObservationFieldSets(
+    from objects: Set<NSManagedObject>
+  ) -> [NSManagedObjectID: CDEObservationFieldSet] {
+    objects.reduce(into: [:]) { result, object in
+      guard object.objectID.isTemporaryID == false else {
+        return
+      }
+      guard let modelType = type(of: object) as? any CDEObservationFieldMapProviding.Type else {
+        return
+      }
+
+      let fieldSet = modelType.__cdObservationFieldSet(
+        forCoreDataKeys: object.changedValues().keys
+      )
+      guard fieldSet.isEmpty == false else {
+        return
+      }
+
+      result[object.objectID] = fieldSet
     }
-    guard let modelType = type(of: object) as? any CDEObservationFieldMapProviding.Type else {
-      return
+  }
+
+  private final class CDEModelActorObservationFallbackLogState: @unchecked Sendable {
+    private let lock = NSLock()
+    private var didLog = false
+
+    func shouldLog() -> Bool {
+      lock.withLock {
+        guard didLog == false else {
+          return false
+        }
+        didLog = true
+        return true
+      }
     }
+  }
 
-    let fieldSet = modelType.__cdObservationFieldSet(
-      forCoreDataKeys: object.changedValues().keys
-    )
-    guard fieldSet.isEmpty == false else {
+  private let cdeModelActorObservationFallbackLogState =
+    CDEModelActorObservationFallbackLogState()
+
+  @available(iOS 17.0, macOS 14.0, tvOS 17.0, watchOS 10.0, visionOS 1.0, *)
+  public func _cdeLogUnboundModelActorObservationSave() {
+    guard cdeModelActorObservationFallbackLogState.shouldLog() else {
       return
     }
-
-    result[object.objectID] = fieldSet
+    NSLog(
+      "CoreDataEvolution Observation warning: saveObservedChanges() was called on an "
+        + "@NSModelActor instance that was not created with init(observationDomain:). "
+        + "Falling back to modelContext.save(); no CDE Observation metadata will be produced."
+    )
   }
-}
+#endif

Sources/CoreDataEvolution/NSMainModelActor.swift

@@ -50,14 +50,16 @@ extension NSMainModelActor {
   }
 }
 
-@available(iOS 17.0, macOS 14.0, tvOS 17.0, watchOS 10.0, visionOS 1.0, *)
-extension NSMainModelActor {
-  /// Saves `viewContext` changes through the active observation domain.
-  ///
-  /// `CDEObservationDomain` instruments `viewContext` directly, so this wrapper is symmetry sugar for
-  /// the main-actor path rather than a separate correctness hook.
-  public func saveObservedChanges(in observation: CDEObservationDomain) throws {
-    _ = observation
-    try modelContext.save()
+#if compiler(>=6.2)
+  @available(iOS 17.0, macOS 14.0, tvOS 17.0, watchOS 10.0, visionOS 1.0, *)
+  extension NSMainModelActor {
+    /// Saves `viewContext` changes through the active observation domain.
+    ///
+    /// `CDEObservationDomain` instruments `viewContext` directly, so this wrapper is symmetry sugar for
+    /// the main-actor path rather than a separate correctness hook.
+    public func saveObservedChanges(in observation: CDEObservationDomain) throws {
+      _ = observation
+      try modelContext.save()
+    }
   }
-}
+#endif