Advanced App Intents for Siri & Apple Intelligence

 import AppIntents
+import CoreSpotlight
 
−// Pre-iOS 27: No interaction donation API existed.
−// Developers could only expose actions via Siri/Shortcuts directly;
−// Apple Intelligence had no way to learn from in-app UI behavior.
−// The only option was to conform to AppIntent and let users invoke via Siri:
+// MARK: - Entity with Ownership
 
+struct MessageRecipient: AppEntity, OwnershipProvidingEntity {
+    static var typeDisplayRepresentation = TypeDisplayRepresentation(name: "Recipient")
+    static var defaultQuery = MessageRecipientQuery()
+
+    var id: String
+    var name: String
+    var isSharedContact: Bool
+
+    var displayRepresentation: DisplayRepresentation {
+        DisplayRepresentation(
+            title: "\(name)",
+            subtitle: isSharedContact ? "Shared contact" : "Private contact",
+            image: .init(systemName: isSharedContact ? "person.2.fill" : "person.fill")
+        )
+    }
+
+    // OwnershipProvidingEntity: tell Siri if this entity is shared/public
+    var ownershipState: EntityOwnershipState {
+        isSharedContact ? .owned : .notOwned
+    }
+}
+
+struct MessageRecipientQuery: EntityQuery {
+    func entities(for identifiers: [String]) async throws -> [MessageRecipient] {
+        identifiers.map { MessageRecipient(id: $0, name: "Contact \($0)", isSharedContact: false) }
+    }
+}
+
+// MARK: - Intent
+
 struct SendMessageIntent: AppIntent {
     static var title: LocalizedStringResource = "Send Message"
+    static var description = IntentDescription("Send a message to a contact.")
 
     @Parameter(title: "Recipient")
−    var recipientName: String
+    var recipient: MessageRecipient
 
     @Parameter(title: "Message")
     var messageBody: String
 
−    func perform() async throws -> some IntentResult {
−        // Send the message
−        // Return empty result — Siri wrote its own generic response
−        return .result()
+    func perform() async throws -> some ProvidesDialog {
+        // Actually send the message here
+        return .result(dialog: IntentDialog(
+            full: "Sent '\(messageBody)' to \(recipient.name).",
+            supporting: "Message sent!"
+        ))
     }
 }
 
−// No IntentDonationManager existed — Apple Intelligence could not
−// learn from actions taken inside the app's own UI.
−// No OwnershipProvidingEntity protocol — Siri could not distinguish
−// shared vs private entities for confirmation decisions.
−// No IndexedEntityQuery — reindexing required Core Spotlight APIs directly.
+// MARK: - Donation from UI
+
+final class ConversationViewModel: ObservableObject {
+    /// Called from the app's compose UI — NOT from an intent
+    func sendMessage(to recipient: MessageRecipient, body: String) async {
+        // 1. Perform the actual send
+        await performActualSend(recipient: recipient, body: body)
+
+        // 2. Donate to Apple Intelligence so it learns this preference
+        var intent = SendMessageIntent()
+        intent.recipient = recipient
+        intent.messageBody = body
+
+        // IntentDonationManager is new in iOS 27
+        try? await IntentDonationManager.shared.donate(intent: intent)
+    }
+
+    private func performActualSend(recipient: MessageRecipient, body: String) async {
+        // Real send logic here
+    }
+}
+
+// MARK: - IndexedEntityQuery for Spotlight reindexing (new in iOS 27)
+
+struct IndexedMessageRecipientQuery: IndexedEntityQuery {
+    typealias Entity = MessageRecipient
+
+    func entities(for identifiers: [String]) async throws -> [MessageRecipient] {
+        identifiers.map { MessageRecipient(id: $0, name: "Contact \($0)", isSharedContact: false) }
+    }
+
+    // Called by Spotlight when it needs a full reindex
+    func suggestedEntities() async throws -> [MessageRecipient] {
+        // Return all entities to index
+        return [
+            MessageRecipient(id: "1", name: "Alice", isSharedContact: false),
+            MessageRecipient(id: "2", name: "Bob", isSharedContact: true)
+        ]
+    }
+}