Refine typed entitlement readiness

Fixtures/ExternalConsumer/Sources/Consumer/main.swift

@@ -17,7 +17,11 @@ struct Consumer {
             }
         )
 
-        print("Active entitlements: \(store.activeEntitlements)")
+        if let activeEntitlements = store.activeEntitlements {
+            print("Active entitlements: \(activeEntitlements)")
+        } else {
+            print("Active entitlements are unresolved")
+        }
         try await store.close()
     }
 }

README.md

@@ -54,7 +54,9 @@ and `Transaction.updates` monitoring during initialization. Retain one instance
 in the application's process-lifetime composition.
 
 `activeEntitlements` contains the app-defined identifiers represented by
-StoreKit's current entitlements. `entitlements` contains the complete verified
+StoreKit's current entitlements. It is `nil` while the initial entitlement
+query is unresolved and becomes a non-`nil` empty set when no known
+subscription is active. `entitlements` contains the complete verified
 snapshot, including product identifiers outside `SubscriptionID`.
 
 ## Use SubscriptionStoreView
@@ -77,8 +79,12 @@ struct PremiumStoreView: View {
 
     var body: some View {
         VStack {
-            if store.activeEntitlements.contains(.yearly) {
-                Label("Premium active", systemImage: "checkmark.seal.fill")
+            if let activeEntitlements = store.activeEntitlements {
+                if activeEntitlements.contains(.yearly) {
+                    Label("Premium active", systemImage: "checkmark.seal.fill")
+                }
+            } else {
+                ProgressView()
             }
 
             SubscriptionStoreView(

Sources/StoreTransactionKit/Store.swift

@@ -28,7 +28,18 @@ where
     public private(set) var entitlements: StoreEntitlements?
 
     /// App-defined identifiers represented by the latest current entitlements.
-    public private(set) var activeEntitlements: Set<EntitlementID> = []
+    ///
+    /// The value is `nil` until the first entitlement query succeeds. An empty
+    /// set is non-`nil` and means none of the app-defined identifiers is
+    /// currently entitled.
+    public var activeEntitlements: Set<EntitlementID>? {
+        entitlements.map { entitlements in
+            Set(
+                entitlements.transactions.compactMap {
+                    EntitlementID(rawValue: $0.productID)
+                })
+        }
+    }
 
     /// The error from the initial entitlement query when startup did not reach
     /// readiness.
@@ -156,10 +167,6 @@ where
 
     fileprivate func apply(_ entitlements: StoreEntitlements) {
         self.entitlements = entitlements
-        activeEntitlements = Set(
-            entitlements.transactions.compactMap {
-                EntitlementID(rawValue: $0.productID)
-            })
         startupError = nil
     }
 

Sources/StoreTransactionKit/StoreTransactionKit.docc/StoreTransactionKit.md

@@ -12,9 +12,12 @@ processor and publishes observable current-entitlement state.
 
 Create one store in the application composition root. Supply an idempotent
 transaction handler that commits the app's business effect before returning.
-The app defines a string-backed entitlement identifier type; ``Store/activeEntitlements``
-then exposes a typed set derived from StoreKit's verified current entitlements.
-Pass direct results from custom purchase UI into ``Store/process(_:)``.
+The app defines a string-backed entitlement identifier type;
+``Store/activeEntitlements`` then exposes an optional typed set derived from
+StoreKit's verified current entitlements. `nil` means the initial entitlement
+query remains unresolved; an empty set means the query completed with no
+matching entitlement. Pass direct results from custom purchase UI into
+``Store/process(_:)``.
 
 The framework owns StoreKit verification, process-local exact-revision
 coalescing, `finish()`, entitlement refresh, history ordering, restore

Tests/StoreTransactionKitTests/StoreTests.swift

@@ -25,6 +25,7 @@ struct StoreTests {
             reportFailure: { _ in }
         )
 
+        #expect(store.activeEntitlements == nil)
         await store.waitForStartup()
 
         #expect(store.activeEntitlements == [.monthly])
@@ -57,10 +58,12 @@ struct StoreTests {
             reportFailure: { _ in }
         )
 
+        #expect(store.activeEntitlements == nil)
         await query.waitForRequest(1)
         await query.fail(TestFailure())
         await store.waitForStartup()
         #expect(store.entitlements == nil)
+        #expect(store.activeEntitlements == nil)
         #expect(store.startupError != nil)
 
         let refresh = Task { try await store.refreshEntitlements() }
@@ -75,6 +78,22 @@ struct StoreTests {
         try await store.close()
     }
 
+    @Test("an empty set means entitlement resolution completed")
+    func emptyTypedEntitlementProjection() async throws {
+        let fixture = TestSourceFixture(currentEntitlements: { [] })
+        fixture.unfinished.finish()
+        let store = Store<SubscriptionID>(
+            source: fixture.source,
+            handleTransaction: { _ in },
+            reportFailure: { _ in }
+        )
+
+        #expect(store.activeEntitlements == nil)
+        await store.waitForStartup()
+        #expect(store.activeEntitlements == Set<SubscriptionID>())
+        try await store.close()
+    }
+
     @Test("the Store facade rejects handler reentry during startup")
     func startupHandlerReentrancy() async throws {
         let fixture = TestSourceFixture()