@tinkerlandai/indiana-react-native 0.9.2 → 0.10.1

package/native-sdk/ios/FeatureClient.swift

@@ -0,0 +1,86 @@
+import Foundation
+
+public struct IndianaFeatureResult: Codable, Sendable {
+    public let value: IndianaJSON
+    public let source: String
+    public let on: Bool
+    public let off: Bool
+    public let ruleId: String
+    public let experimentResult: IndianaJSON?
+}
+
+#if canImport(UIKit)
+import UIKit
+
+/// Local and private/remote Feature evaluation share the SDK's packaged GB engine.
+/// The hidden shell receives no Customer Token; HTTP and identity remain native.
+@MainActor public final class IndianaFeatureClient {
+    private let configuration: IndianaConfiguration
+    private let attributes: [String: IndianaJSON]
+    private let operation: @Sendable (IndianaCustomerOperation, [String: IndianaJSON]) async throws -> IndianaJSON
+    private var host: IndianaBundledWebView!
+    public var onError: (@MainActor (Error) -> Void)?
+    private var ready = false
+    private var stopped = false
+    private var readiness: [CheckedContinuation<Void, Error>] = []
+    private var pending: [UUID: CheckedContinuation<IndianaJSON, Error>] = [:]
+    init(configuration: IndianaConfiguration, attributes: [String: IndianaJSON], operation: @escaping @Sendable (IndianaCustomerOperation, [String: IndianaJSON]) async throws -> IndianaJSON) {
+        self.configuration = configuration; self.attributes = attributes; self.operation = operation
+        host = IndianaBundledWebView(label: "Indiana Feature evaluator", dispatch: { [weak self] method, payload in
+            guard let self else { throw IndianaClientError.identityChanged }; return try await self.dispatch(method, payload)
+        }, onError: { [weak self] error in guard let self else { return }; if !self.ready { self.close() } else { self.onError?(error) } })
+        host.start()
+        Task { [weak self] in try? await Task.sleep(nanoseconds: 45_000_000_000); if let self, !self.ready { self.close() } }
+    }
+    public func evalFeature(_ key: String) async throws -> IndianaFeatureResult {
+        let value = try await call(["method": .string("evalFeature"), "key": .string(key)])
+        let data = try JSONEncoder().encode(value)
+        try IndianaSchema.validate("nativeFeatureResult", data: data)
+        return try JSONDecoder().decode(IndianaFeatureResult.self, from: data)
+    }
+    public func isOn(_ key: String) async throws -> Bool { try await evalFeature(key).on }
+    public func isOff(_ key: String) async throws -> Bool { try await evalFeature(key).off }
+    public func getFeatureValue(_ key: String, fallback: IndianaJSON = .null) async throws -> IndianaJSON { try await call(["method": .string("getFeatureValue"), "key": .string(key), "fallback": fallback]) }
+    public func setAttributes(_ value: [String: IndianaJSON]) async throws { _ = try await call(["method": .string("setAttributes"), "attributes": .object(value)]) }
+    public func refresh() async throws { _ = try await call(["method": .string("refresh")]) }
+    public func flush() async throws { _ = try await call(["method": .string("flush")]) }
+    public func close() {
+        guard !stopped else { return }; stopped = true; host?.destroy()
+        let waiting = readiness; readiness = []; for continuation in waiting { continuation.resume(throwing: IndianaClientError.identityChanged) }
+        let calls = pending; pending = [:]; for continuation in calls.values { continuation.resume(throwing: IndianaClientError.identityChanged) }
+    }
+    private func call(_ command: [String: IndianaJSON]) async throws -> IndianaJSON {
+        guard !stopped else { throw IndianaClientError.identityChanged }
+        if !ready { try await withCheckedThrowingContinuation { readiness.append($0) } }
+        guard !stopped else { throw IndianaClientError.identityChanged }
+        let id = UUID()
+        return try await withCheckedThrowingContinuation { continuation in
+            pending[id] = continuation
+            host.send(.object(["event": .string("feature_call"), "id": .string(id.uuidString.lowercased()), "input": .object(command)]))
+            Task { [weak self] in
+                try? await Task.sleep(nanoseconds: 45_000_000_000)
+                self?.pending.removeValue(forKey: id)?.resume(throwing: IndianaClientError.temporaryUnavailable)
+            }
+        }
+    }
+    private func dispatch(_ method: String, _ value: IndianaJSON) async throws -> IndianaJSON {
+        switch method {
+        case "ready":
+            host.send(.object(["event": .string("init"), "surface": .string("features"), "scope": .object(["projectId": .string(configuration.scope.projectId.uuidString.lowercased()), "environment": .string(configuration.scope.environment.rawValue)]), "apiOrigin": .string(configuration.apiOrigin), "attributes": .object(attributes)])); return .null
+        case "featureOperation":
+            guard !stopped, let name = value.object?["operation"]?.string,
+                  ["getFeatures", "evaluateFeatures", "trackEvents"].contains(name), let selected = IndianaCustomerOperation(rawValue: name),
+                  let input = value.object?["input"]?.object else { throw IndianaFunnelError.invalidCommand }
+            return try await operation(selected, input)
+        case "featuresReady":
+            guard !stopped else { throw IndianaClientError.identityChanged }; ready = true
+            let waiting = readiness; readiness = []; for continuation in waiting { continuation.resume() }; return .null
+        case "featureResult":
+            guard !stopped, let id = value.object?["id"]?.string.flatMap(UUID.init(uuidString:)), let continuation = pending.removeValue(forKey: id) else { return .null }
+            if value.object?["error"] != nil { continuation.resume(throwing: IndianaClientError.invalidResponse) }
+            else { continuation.resume(returning: value.object?["result"] ?? .null) }; return .null
+        default: throw IndianaFunnelError.invalidCommand
+        }
+    }
+}
+#endif

package/native-sdk/ios/FunnelCommandStorage.swift

@@ -0,0 +1,163 @@
+import Foundation
+import Security
+import CryptoKit
+import Darwin
+
+public struct IndianaFunnelStorageSnapshot: Sendable {
+    public let revision: Int
+    public let entry: Data?
+    public init(revision: Int, entry: Data?) { self.revision = revision; self.entry = entry }
+}
+/// One original Run per adapter. CAS must be atomic across all participating hosts.
+public protocol IndianaFunnelCommandStorage: Sendable {
+    func read() async throws -> IndianaFunnelStorageSnapshot
+    func write(expectedRevision: Int, entry: Data?) async throws -> Int?
+}
+
+/// This-device-only storage. Neither Run nor Customer credentials are persisted.
+actor IndianaFunnelCommandKeychain: IndianaFunnelCommandStorage {
+    private let service: String
+    private let lockURL: URL
+    private struct Stored: Codable { let revision: Int; let entry: Data? }
+    init(configuration: IndianaConfiguration, runToken: String) throws {
+        let namespace = "\(configuration.baseURL.absoluteString)|\(configuration.scope.projectId)|\(configuration.scope.environment.rawValue)|\(runToken)"
+        let hash = SHA256.hash(data: Data(namespace.utf8)).map { String(format: "%02x", $0) }.joined()
+        service = "\(Bundle.main.bundleIdentifier ?? "Indiana").indiana.funnel.commands.v1.\(hash)"
+        let folder = try FileManager.default.url(for: .applicationSupportDirectory, in: .userDomainMask, appropriateFor: nil, create: true).appendingPathComponent("IndianaFunnelCommandLocks", isDirectory: true)
+        try FileManager.default.createDirectory(at: folder, withIntermediateDirectories: true, attributes: [.posixPermissions: 0o700])
+        lockURL = folder.appendingPathComponent(hash + ".lock")
+    }
+    private var query: [String: Any] { [kSecClass as String: kSecClassGenericPassword, kSecAttrService as String: service, kSecAttrAccount as String: "snapshot"] }
+    private func locked<T>(_ work: () throws -> T) throws -> T {
+        let fd = open(lockURL.path, O_CREAT | O_RDWR, 0o600)
+        guard fd >= 0 else { throw IndianaClientError.protectedStorageUnavailable }
+        defer { Darwin.close(fd) }
+        guard flock(fd, LOCK_EX) == 0 else { throw IndianaClientError.protectedStorageUnavailable }
+        defer { flock(fd, LOCK_UN) }
+        return try work()
+    }
+    private func stored() throws -> Stored {
+        var result: CFTypeRef?
+        let status = SecItemCopyMatching(query.merging([kSecReturnData as String: true]) { _, new in new } as CFDictionary, &result)
+        if status == errSecItemNotFound { return Stored(revision: 0, entry: nil) }
+        guard status == errSecSuccess, let bytes = result as? Data, bytes.count <= 1_048_576,
+              let value = try? JSONDecoder().decode(Stored.self, from: bytes), value.revision >= 0 else { throw IndianaClientError.protectedStorageUnavailable }
+        return value
+    }
+    func read() throws -> IndianaFunnelStorageSnapshot { try locked { let value = try stored(); return IndianaFunnelStorageSnapshot(revision: value.revision, entry: value.entry) } }
+    func write(expectedRevision: Int, entry: Data?) throws -> Int? {
+        try locked {
+            let previous = try stored()
+            guard previous.revision == expectedRevision else { return nil }
+            guard expectedRevision < Int.max, (entry?.count ?? 0) <= 600_000 else { throw IndianaClientError.protectedStorageUnavailable }
+            let bytes = try JSONEncoder().encode(Stored(revision: expectedRevision + 1, entry: entry))
+            let status = SecItemUpdate(query as CFDictionary, [kSecValueData as String: bytes] as CFDictionary)
+            if status == errSecItemNotFound {
+                let added = SecItemAdd(query.merging([kSecValueData as String: bytes, kSecAttrAccessible as String: kSecAttrAccessibleWhenUnlockedThisDeviceOnly]) { _, new in new } as CFDictionary, nil)
+                guard added == errSecSuccess else { throw IndianaClientError.protectedStorageUnavailable }
+            } else if status != errSecSuccess { throw IndianaClientError.protectedStorageUnavailable }
+            return expectedRevision + 1
+        }
+    }
+}
+
+struct IndianaFunnelRecoveryRecord: Codable, Sendable, Equatable {
+    let schemaVersion: Int
+    let scope: IndianaScope
+    let runId: UUID
+    let funnelId: UUID
+    let versionId: UUID
+    var command: [String: IndianaJSON]?
+    var closeCommand: [String: IndianaJSON]?
+    var purchase: [String: IndianaJSON]?
+    var closed: Bool
+    func matches(_ run: IndianaFunnelRun) -> Bool { run.id == runId && run.source.id == funnelId && run.source.versionId == versionId }
+}
+actor IndianaFunnelCommandJournal {
+    private let storage: any IndianaFunnelCommandStorage
+    private let scope: IndianaScope
+    private var revision = 0
+    private var binding: IndianaFunnelRecoveryRecord?
+    private var updateTail: Task<Void, Never>?
+    init(storage: any IndianaFunnelCommandStorage, scope: IndianaScope) { self.storage = storage; self.scope = scope }
+    private func read() async throws -> (Int, IndianaFunnelRecoveryRecord?) {
+        let saved = try await storage.read()
+        guard saved.revision >= 0 else { throw IndianaFunnelError.invalidResponse }
+        guard let bytes = saved.entry else { return (saved.revision, nil) }
+        guard bytes.count <= 600_000 else { throw IndianaFunnelError.invalidResponse }
+        let record = try JSONDecoder().decode(IndianaFunnelRecoveryRecord.self, from: bytes)
+        guard record.schemaVersion == 1, record.scope == scope, record.command != nil || record.purchase != nil,
+              record.closeCommand == nil || record.command != nil && record.command?["operation"] != .string("close") && record.command?["requestId"] != record.closeCommand?["requestId"] else { throw IndianaFunnelError.invalidResponse }
+        for command in [record.command, record.closeCommand].compactMap({ $0 }) {
+            guard command["customerToken"] == nil, !["start", "get", "review"].contains(command["operation"]?.string ?? "") else { throw IndianaFunnelError.invalidCommand }
+            try IndianaSchema.validate("command", data: JSONEncoder().encode(IndianaJSON.object(command)))
+        }
+        if let purchase = record.purchase {
+            guard Set(purchase.keys) == Set(["receiptId", "operationId", "generation"]),
+                  UUID(uuidString: purchase["receiptId"]?.string ?? "") != nil, UUID(uuidString: purchase["operationId"]?.string ?? "") != nil,
+                  case .number(let generation) = purchase["generation"], generation >= 0, generation.rounded() == generation else { throw IndianaFunnelError.invalidResponse }
+        }
+        return (saved.revision, record)
+    }
+    func load() async throws -> IndianaFunnelRecoveryRecord? { let saved = try await read(); revision = saved.0; binding = saved.1; return saved.1 }
+    func bind(_ run: IndianaFunnelRun) throws { if let binding, !binding.matches(run) { throw IndianaFunnelError.invalidResponse } }
+    private func update(_ change: @escaping @Sendable (IndianaFunnelRecoveryRecord?, Int) throws -> IndianaFunnelRecoveryRecord?) async throws {
+        let previous = updateTail
+        let job = Task { if let previous { await previous.value }; try await apply(change) }
+        updateTail = Task { _ = try? await job.value }
+        try await job.value
+    }
+    private func apply(_ change: @Sendable (IndianaFunnelRecoveryRecord?, Int) throws -> IndianaFunnelRecoveryRecord?) async throws {
+        for _ in 0..<4 {
+            let saved = try await read()
+            if let binding, let current = saved.1, binding.runId != current.runId || binding.versionId != current.versionId || binding.funnelId != current.funnelId { throw IndianaFunnelError.commandPending }
+            let next = try change(saved.1, saved.0)
+            if next == saved.1 { revision = saved.0; return }
+            let bytes = try next.map { try JSONEncoder().encode($0) }
+            if let nextRevision = try await storage.write(expectedRevision: saved.0, entry: bytes) { revision = nextRevision; binding = next ?? binding; return }
+        }
+        throw IndianaFunnelError.commandPending
+    }
+    func retain(_ command: [String: IndianaJSON], run: IndianaFunnelRun) async throws {
+        let bytes = try JSONEncoder().encode(IndianaJSON.object(command))
+        guard command["customerToken"] == nil, bytes.count <= 262144, !["start", "get", "review"].contains(command["operation"]?.string ?? "") else { throw IndianaFunnelError.invalidCommand }
+        try IndianaSchema.validate("command", data: bytes)
+        try bind(run)
+        let scope = self.scope
+        let knownRevision = revision
+        try await update { saved, currentRevision in
+            var value = saved ?? IndianaFunnelRecoveryRecord(schemaVersion: 1, scope: scope, runId: run.id, funnelId: run.source.id, versionId: run.source.versionId, closed: false)
+            guard value.matches(run), saved != nil || currentRevision == knownRevision || command["operation"] == .string("close") else { throw IndianaFunnelError.commandPending }
+            if command["operation"] == .string("close") {
+                value.closed = true
+                if let original = value.command, original["operation"] != .string("close") {
+                    guard original["requestId"] != command["requestId"], value.closeCommand == nil || value.closeCommand == command else { throw IndianaFunnelError.commandPending }; value.closeCommand = command
+                } else { guard value.command == nil || value.command == command else { throw IndianaFunnelError.commandPending }; value.command = command }
+            } else { guard value.command == nil || value.command == command else { throw IndianaFunnelError.commandPending }; value.command = command }
+            return value
+        }
+    }
+    func purchase(_ purchase: [String: IndianaJSON], terminal: Bool, run: IndianaFunnelRun) async throws {
+        try bind(run); let knownRevision = revision
+        let scope = self.scope
+        try await update { saved, currentRevision in
+            if saved == nil && currentRevision != knownRevision { throw IndianaFunnelError.commandPending }
+            var value = saved ?? IndianaFunnelRecoveryRecord(schemaVersion: 1, scope: scope, runId: run.id, funnelId: run.source.id, versionId: run.source.versionId, closed: false)
+            if case .number(let old) = value.purchase?["generation"], case .number(let next) = purchase["generation"] {
+                if old > next { return saved }
+                if old == next && value.purchase?["operationId"] != purchase["operationId"] { throw IndianaFunnelError.commandPending }
+            }
+            if terminal { if value.purchase?["operationId"] == purchase["operationId"] { value.purchase = nil } }
+            else { value.purchase = purchase }
+            return value.command == nil && value.purchase == nil ? nil : value
+        }
+    }
+    func settle(_ id: String) async throws {
+        try await update { saved, _ in
+            guard var value = saved else { return nil }
+            if value.command?["requestId"] == .string(id) { value.command = value.closeCommand; value.closeCommand = nil }
+            else if value.closeCommand?["requestId"] == .string(id) { value.closeCommand = nil }
+            return value.command == nil && value.purchase == nil ? nil : value
+        }
+    }
+}

package/native-sdk/ios/FunnelConfigurationRelay.swift

@@ -0,0 +1,48 @@
+import Foundation
+
+/// The Funnel shell has no network access (`connect-src 'none'`). For Local rules it asks the native host
+/// for public configuration: one exact GET, without credentials, cookies or redirects.
+final class IndianaFunnelConfigurationRelay: Sendable {
+    static let maxBytes = 1_048_576
+    static let headers: Set<String> = ["age", "content-type", "date", "etag", "retry-after", "x-indiana-config-valid-until", "x-indiana-config-validated-at"]
+    private let baseURL: URL
+    private let session: URLSession
+    init(configuration: IndianaConfiguration, sessionConfiguration: URLSessionConfiguration = .ephemeral) {
+        baseURL = configuration.baseURL
+        let config = sessionConfiguration.copy() as! URLSessionConfiguration
+        config.urlCache = nil; config.httpCookieStorage = nil; config.httpShouldSetCookies = false; config.requestCachePolicy = .reloadIgnoringLocalCacheData
+        config.timeoutIntervalForRequest = configuration.timeout; config.timeoutIntervalForResource = configuration.timeout
+        session = URLSession(configuration: config, delegate: RefuseRedirect(), delegateQueue: nil)
+    }
+    deinit { session.invalidateAndCancel() }
+    func read(_ payload: IndianaJSON) async throws -> IndianaJSON {
+        guard let object = payload.object, object.count == 1, let path = object["path"]?.string,
+              path.range(of: "^/api/v1/configuration/[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}(/artifacts/[a-f0-9]{64})?$", options: .regularExpression) != nil,
+              let url = URL(string: path, relativeTo: baseURL)?.absoluteURL else { throw IndianaFunnelError.invalidCommand }
+        var request = URLRequest(url: url); request.httpMethod = "GET"
+        request.cachePolicy = path.contains("/artifacts/") ? .useProtocolCachePolicy : .reloadIgnoringLocalCacheData
+        do {
+            let (bytes, response) = try await session.bytes(for: request)
+            guard let http = response as? HTTPURLResponse else { throw IndianaClientError.temporaryUnavailable }
+            var headers: [String: IndianaJSON] = [:]
+            for (key, value) in http.allHeaderFields {
+                if let key = (key as? String)?.lowercased(), Self.headers.contains(key), let value = value as? String { headers[key] = .string(value) }
+            }
+            var data = Data()
+            // The shell reports other statuses (including 429 Retry-After) by status alone.
+            if (200..<300).contains(http.statusCode) {
+                if response.expectedContentLength > Self.maxBytes { throw IndianaClientError.invalidResponse }
+                for try await byte in bytes {
+                    guard data.count < Self.maxBytes else { throw IndianaClientError.invalidResponse }
+                    data.append(byte)
+                }
+            }
+            guard let body = String(data: data, encoding: .utf8) else { throw IndianaClientError.invalidResponse }
+            return .object(["status": .number(Double(http.statusCode)), "headers": .object(headers), "body": .string(body)])
+        } catch let error as IndianaClientError { throw error }
+        catch { throw IndianaClientError.temporaryUnavailable }
+    }
+    private final class RefuseRedirect: NSObject, URLSessionTaskDelegate, Sendable {
+        func urlSession(_ session: URLSession, task: URLSessionTask, willPerformHTTPRedirection response: HTTPURLResponse, newRequest request: URLRequest, completionHandler: @escaping (URLRequest?) -> Void) { completionHandler(nil) }
+    }
+}

package/native-sdk/ios/FunnelSession.swift

@@ -0,0 +1,232 @@
+import Foundation
+
+public indirect enum IndianaJSON: Codable, Sendable, Equatable {
+    case object([String: IndianaJSON]), array([IndianaJSON]), string(String), number(Double), bool(Bool), null
+    public init(from decoder: Decoder) throws {
+        let c = try decoder.singleValueContainer()
+        if c.decodeNil() { self = .null }
+        else if let v = try? c.decode(Bool.self) { self = .bool(v) }
+        else if let v = try? c.decode(String.self) { self = .string(v) }
+        else if let v = try? c.decode(Double.self), v.isFinite { self = .number(v) }
+        else if let v = try? c.decode([String: IndianaJSON].self) { self = .object(v) }
+        else { self = .array(try c.decode([IndianaJSON].self)) }
+    }
+    public func encode(to encoder: Encoder) throws {
+        var c = encoder.singleValueContainer()
+        switch self { case .object(let v): try c.encode(v); case .array(let v): try c.encode(v); case .string(let v): try c.encode(v); case .number(let v): try c.encode(v); case .bool(let v): try c.encode(v); case .null: try c.encodeNil() }
+    }
+    var object: [String: IndianaJSON]? { if case .object(let value) = self { return value }; return nil }
+    var string: String? { if case .string(let value) = self { return value }; return nil }
+}
+public struct IndianaExecutionSource: Codable, Sendable, Equatable { public let type: String; public let id: UUID; public let versionId: UUID }
+public struct IndianaFunnelRun: Codable, Sendable {
+    public let id: UUID; public let source: IndianaExecutionSource
+    public let revision: Int; public let visit: Int; public let nodeId: String; public let nodeType: String; public let status: String
+    public let canBack: Bool; public let authenticated: Bool; public let locale: String
+    public let answers: [String: IndianaJSON]; public let parameters: [String: IndianaJSON]; public let variables: [String: IndianaJSON]
+    public let output: IndianaJSON?; public let screen: IndianaJSON?; public let paywall: IndianaJSON?; public let instruction: IndianaJSON?
+    public let runExpiresAt: String; public let credentialExpiresAt: String?; public let pendingRequest: Pending?
+    public struct Pending: Codable, Sendable { public let requestId: UUID; public let authenticationRequired: Bool }
+}
+public enum IndianaFunnelError: Error { case invalidCommand, commandPending, invalidResponse, identityChanged, pendingPayment }
+/// A Funnel session owns navigation only. Native receipt recovery and financial operations belong to IndianaClient.
+public actor IndianaFunnelSession {
+    private let configuration: IndianaConfiguration; private let http: any IndianaHTTP; private let runToken: String
+    private var publicPaywallContent: (@Sendable (IndianaJSON) async throws -> IndianaJSON)?
+    private var publicPresentation: [String: IndianaJSON]?
+    private let journal: IndianaFunnelCommandJournal?
+    private var restoration: Task<IndianaFunnelRecoveryRecord?, Error>?
+    private var restored = false
+    public private(set) var pendingPurchase: [String: IndianaJSON]?
+    private var customerToken: String?; private var epoch = UUID(); private var pending: [String: IndianaJSON]?; private var sending = false; private var closingCommand: [String: IndianaJSON]?; private var closeRequested = false; private var uncertain = Set<String>(); private var settlements: [String: String] = [:]
+    private var invalidated = false; private var invalidation: (@Sendable () -> Void)?; private var response: Data?
+    public private(set) var current: IndianaFunnelRun?
+    public init(configuration: IndianaConfiguration, runToken: String, commandStorage: (any IndianaFunnelCommandStorage)? = nil) throws {
+        guard runToken.range(of: "^gg_fr_[A-Za-z0-9_-]{43}$", options: .regularExpression) != nil else { throw IndianaFunnelError.invalidCommand }
+        self.configuration = configuration;self.http = IndianaURLTransport(configuration: configuration);self.runToken = runToken
+        journal = IndianaFunnelCommandJournal(storage: try commandStorage ?? IndianaFunnelCommandKeychain(configuration: configuration, runToken: runToken), scope: configuration.scope)
+    }
+    init(configuration: IndianaConfiguration, http: any IndianaHTTP, runToken: String, commandStorage: (any IndianaFunnelCommandStorage)? = nil, publicPaywallContent: (@Sendable (IndianaJSON) async throws -> IndianaJSON)? = nil) throws {
+        self.publicPaywallContent = publicPaywallContent
+        guard runToken.range(of: "^gg_fr_[A-Za-z0-9_-]{43}$", options: .regularExpression) != nil else { throw IndianaFunnelError.invalidCommand }
+        self.configuration = configuration;self.http = http;self.runToken = runToken
+        journal = commandStorage.map { IndianaFunnelCommandJournal(storage: $0, scope: configuration.scope) }
+    }
+    private func restoreCommands() async throws {
+        guard !restored, let journal else { return }
+        if restoration == nil { restoration = Task { try await journal.load() } }
+        let original = epoch
+        let record = try await restoration!.value
+        guard original == epoch, !invalidated else { throw IndianaFunnelError.identityChanged }
+        if restored { return }; restored = true
+        pending = record?.command; closingCommand = record?.closeCommand; pendingPurchase = record?.purchase; closeRequested = record?.closed == true || pending?["operation"] == .string("close")
+        for command in [pending, closingCommand].compactMap({ $0 }) { if let id = command["requestId"]?.string { uncertain.insert(id) } }
+    }
+    public func identify(customerToken: String) throws {
+        guard !invalidated, customerToken.range(of: "^gg_ct_[A-Za-z0-9_-]{32,128}$", options: .regularExpression) != nil else { throw IndianaClientError.unauthenticated }
+        epoch = UUID();self.customerToken = customerToken;response = nil;publicPresentation = nil
+    }
+    public func reset() { epoch = UUID();invalidated = true;customerToken = nil;pending = nil;closingCommand = nil;pendingPurchase = nil;uncertain.removeAll();settlements.removeAll();current = nil;response = nil;publicPresentation = nil;invalidation?();invalidation = nil }
+    func hostConfiguration() -> IndianaConfiguration { configuration }
+    func onInvalidation(_ callback: @escaping @Sendable () -> Void) { invalidation = callback;if invalidated { callback() } }
+    func hostPendingCommand() -> IndianaJSON { (closingCommand ?? pending).map(IndianaJSON.object) ?? .null }
+    private func request(_ command: [String: IndianaJSON]) async throws -> IndianaFunnelRun {
+        try await restoreCommands()
+        guard !invalidated else { throw IndianaFunnelError.identityChanged }
+        let original = epoch;var body = command;if let customerToken { body["customerToken"] = .string(customerToken) }
+        let encoder = JSONEncoder();encoder.outputFormatting = [.sortedKeys];let input = try encoder.encode(body)
+        guard input.count <= 262144 else { throw IndianaFunnelError.invalidCommand };try IndianaSchema.validate("command", data: input)
+        let bytes = try await http.send(path: "funnels", method: "POST", authorization: runToken, body: input)
+        guard original == epoch, !invalidated else { throw IndianaFunnelError.identityChanged }
+        try IndianaSchema.validate("response", data: bytes)
+        struct WireScope: Decodable { let scope: IndianaScope }
+        guard try JSONDecoder().decode(WireScope.self, from: bytes).scope == configuration.scope else { throw IndianaFunnelError.invalidResponse }
+        struct Reply: Decodable { let scope: IndianaScope; let run: IndianaFunnelRun }
+        let reply = try JSONDecoder().decode(Reply.self, from: bytes)
+        let object = try JSONDecoder().decode(IndianaJSON.self, from: bytes).object
+        if let id = command["settlementRequestId"]?.string ?? command["requestId"]?.string {
+            guard object?["settlement"]?.object?["requestId"] == .string(id) else { throw IndianaFunnelError.invalidResponse }
+        }
+        guard reply.scope == configuration.scope, reply.run.source.type == "funnel" else { throw IndianaFunnelError.invalidResponse }
+        try await journal?.bind(reply.run)
+        guard original == epoch, !invalidated else { throw IndianaFunnelError.identityChanged }
+        if let current, current.id != reply.run.id || current.source != reply.run.source || current.locale != reply.run.locale || current.parameters != reply.run.parameters { throw IndianaFunnelError.invalidResponse }
+        if let instruction = reply.run.instruction?.object, instruction["type"] == .string("open_url") {
+            guard let text = instruction["url"]?.string, let url = URL(string: text), url.scheme == "https", url.host != nil, url.user == nil, url.password == nil else { throw IndianaFunnelError.invalidResponse }
+        }
+        if let settlement = object?["settlement"]?.object, let id = settlement["requestId"]?.string, let state = settlement["state"]?.string { settlements[id] = state }
+        if let previous = current?.paywall?.object, let incoming = reply.run.paywall?.object, previous["receiptId"] == incoming["receiptId"],
+           previous["resolution"]?.object?["content"]?.object?["artifact"]?.object?["sha256"] != incoming["resolution"]?.object?["content"]?.object?["artifact"]?.object?["sha256"] { throw IndianaFunnelError.invalidResponse }
+        if let current, let previous = current.paywall?.object, let incoming = reply.run.paywall?.object,
+           previous["receiptId"] == incoming["receiptId"], case .number(let old) = previous["selectionGeneration"],
+           case .number(let next) = incoming["selectionGeneration"], next < old { return current }
+        if journal != nil, command["operation"] != .string("review"), current == nil || reply.run.revision >= current!.revision {
+            let purchase = reply.run.paywall?.object ?? object?["purchase"]?.object
+            let operation = purchase?["operation"]?.object
+            let rawSettlement = object?["settlement"]?.object
+            let paywall = reply.run.paywall?.object
+            let settlement = (paywall == nil || paywall?["purchaseRequestId"] == rawSettlement?["requestId"]) &&
+                (pendingPurchase == nil || pendingPurchase?["operationId"] == rawSettlement?["operationId"]) ? rawSettlement : nil
+            if let receipt = purchase?["receiptId"] ?? settlement?["receiptId"], receipt != .null,
+               let operationId = operation?["operationId"] ?? purchase?["quote"]?.object?["operationId"] ?? settlement?["operationId"], operationId != .null {
+                let generation = reply.run.paywall?.object?["selectionGeneration"] ?? pendingPurchase?["generation"] ?? .number(0)
+                let reference: [String: IndianaJSON] = ["receiptId": receipt, "operationId": operationId, "generation": generation]
+                let terminal = operation?["status"] == .string("complete") || purchase?["canReselect"] == .bool(true)
+                let stale: Bool
+                if case .number(let old) = pendingPurchase?["generation"], case .number(let next) = generation { stale = next < old } else { stale = false }
+                if !stale {
+                    try await journal?.purchase(reference, terminal: terminal, run: reply.run)
+                    guard original == epoch, !invalidated else { throw IndianaFunnelError.identityChanged }
+                    if !terminal { pendingPurchase = reference } else if pendingPurchase?["operationId"] == operationId { pendingPurchase = nil }
+                }
+            }
+        }
+        guard original == epoch, !invalidated else { throw IndianaFunnelError.identityChanged }
+        if current == nil || reply.run.revision >= current!.revision { response = bytes; current = reply.run };return current!
+    }
+    public func get(data: [String: IndianaJSON]? = nil, purchase: [String: IndianaJSON]? = nil) async throws -> IndianaFunnelRun {
+        try await restoreCommands()
+        var command: [String: IndianaJSON] = ["operation": .string("get")];if let data { command["data"] = .object(data) }
+        if let purchase { command["purchase"] = .object(purchase) }
+        else if let reference = pendingPurchase, let receipt = reference["receiptId"], let operation = reference["operationId"] { command["purchase"] = .object(["receiptId": receipt, "operationId": operation]) }
+        return try await request(command)
+    }
+    private func mutate(_ command: [String: IndianaJSON]) async throws -> IndianaFunnelRun {
+        try await restoreCommands()
+        let closing = command["operation"] == .string("close"), id = command["requestId"]?.string ?? ""
+        if closeRequested && !closing { throw IndianaFunnelError.commandPending }
+        if sending && !closing { throw IndianaFunnelError.commandPending }
+        if closing {
+            closeRequested = true
+            if let closingCommand, closingCommand != command { throw IndianaFunnelError.commandPending }
+            closingCommand = command
+        } else {
+            if let pending, pending != command { throw IndianaFunnelError.commandPending };pending = command
+        }
+        let wasUncertain = uncertain.contains(id);uncertain.insert(id);sending = true;let original = epoch
+        defer { sending = false }
+        do {
+            if let journal { guard let current else { throw IndianaFunnelError.invalidCommand }; try await journal.retain(command, run: current) }
+            let run = try await request(command)
+            let settled = settlements[id] == "settled"
+            if original == epoch, run.pendingRequest?.requestId.uuidString.lowercased() != id,
+               settled,
+               (!closeRequested || closing || settled && !["running", "waiting"].contains(run.status)) {
+                try await journal?.settle(id)
+                if pending == command { pending = nil };if closingCommand == command { closingCommand = nil };uncertain.remove(id)
+            }
+            return run
+        } catch {
+            if original == epoch, !wasUncertain, !closeRequested, let failure = error as? IndianaClientError, case .requestFailed(let status) = failure, status < 500, status != 401, status != 425 { try await journal?.settle(id); if pending == command { pending = nil };uncertain.remove(id) }
+            throw error
+        }
+    }
+    public func settle(requestId: UUID) async throws -> IndianaFunnelRun {
+        let id = requestId.uuidString.lowercased();settlements.removeValue(forKey: id);let run = try await request(["operation": .string("get"), "settlementRequestId": .string(id)])
+        guard let state = settlements[id] else { throw IndianaFunnelError.invalidResponse }
+        if state == "settled" { try await journal?.settle(id); if pending?["requestId"] == .string(id) { pending = nil };if closingCommand?["requestId"] == .string(id) { closingCommand = nil };uncertain.remove(id) };return run
+    }
+    private func base(_ operation: String, requestId: UUID) throws -> [String: IndianaJSON] {
+        guard let current, !invalidated else { throw IndianaFunnelError.invalidCommand }
+        return ["operation": .string(operation), "requestId": .string(requestId.uuidString.lowercased()), "nodeId": .string(current.nodeId), "visit": .number(Double(current.visit)), "revision": .number(Double(current.revision))]
+    }
+    public func submit(output: String, answers: [String: IndianaJSON], selection: [String: IndianaJSON] = [:], requestId: UUID = UUID()) async throws -> IndianaFunnelRun {
+        var command = try base("submit", requestId: requestId);command["input"] = .object(["type": .string("screen"), "output": .string(output), "answers": .object(answers), "selection": .object(selection)]);return try await mutate(command)
+    }
+    public func submit(input: [String: IndianaJSON], requestId: UUID = UUID()) async throws -> IndianaFunnelRun { var command = try base("submit", requestId: requestId);command["input"] = .object(input);return try await mutate(command) }
+    public func back(requestId: UUID = UUID()) async throws -> IndianaFunnelRun { try await mutate(base("back", requestId: requestId)) }
+    public func shown(requestId: UUID = UUID()) async throws -> IndianaFunnelRun { try await mutate(base("shown", requestId: requestId)) }
+    public func close(requestId: UUID = UUID()) async throws -> IndianaFunnelRun { try await mutate(base("close", requestId: requestId)) }
+    public func retry() async throws -> IndianaFunnelRun { try await restoreCommands();if current == nil { _ = try await get() };if let closingCommand { return try await mutate(closingCommand) };guard let pending else { throw IndianaFunnelError.invalidCommand };if closeRequested, let id = pending["requestId"]?.string, let requestId = UUID(uuidString: id) { return try await settle(requestId: requestId) };return try await mutate(pending) }
+    public func resume(requestId: UUID) async throws -> IndianaFunnelRun { try await restoreCommands();if current == nil { _ = try await get() };if closeRequested { return try await settle(requestId: requestId) };if let pending { guard pending["requestId"] == .string(requestId.uuidString.lowercased()) else { throw IndianaFunnelError.commandPending };return try await mutate(pending) };return try await mutate(["operation": .string("resume"), "requestId": .string(requestId.uuidString.lowercased())]) }
+    func hostCommand(_ command: [String: IndianaJSON]) async throws -> Data {
+        guard let operation = command["operation"]?.string, operation != "start", command["customerToken"] == nil else { throw IndianaFunnelError.invalidCommand }
+        if operation == "get" { if let id = command["settlementRequestId"]?.string, let requestId = UUID(uuidString: id) { _ = try await settle(requestId: requestId) } else { _ = try await get(data: command["data"]?.object, purchase: command["purchase"]?.object) } }
+        else if operation == "review" { _ = try await request(command) }
+        else { _ = try await mutate(command) };return try hostResponse()
+    }
+    func hostResponse() throws -> Data { guard let response, !invalidated else { throw IndianaFunnelError.identityChanged };return response }
+    /// Display-only read. Never called by command settlement or purchase recovery.
+    func hostPaywallContent(_ payload: IndianaJSON) async throws -> IndianaJSON {
+        guard !invalidated, let request = payload.object, Set(request.keys) == ["id", "sha256"],
+              let paywall = current?.paywall?.object, let delivery = paywall["resolution"], let value = delivery.object,
+              request["id"] == value["id"], request["sha256"] == value["content"]?.object?["artifact"]?.object?["sha256"] else { throw IndianaFunnelError.invalidCommand }
+        let original = epoch
+        let loaded = try await (publicPaywallContent ?? { try await IndianaPaywallContent(configuration: self.configuration).resolve($0) })(delivery)
+        guard original == epoch, !invalidated else { throw IndianaFunnelError.identityChanged }
+        try IndianaSchema.validate("paywallResolution", data: JSONEncoder().encode(loaded))
+        guard let hydrated = loaded.object, IndianaPaywallContent.validatesHydration(hydrated, delivery: value),
+              let active = current?.paywall?.object, active["receiptId"] == paywall["receiptId"],
+              var latest = active["resolution"]?.object, latest["id"] == value["id"], latest["content"] == value["content"] else { throw IndianaFunnelError.invalidResponse }
+        IndianaPaywallContent.applyPresentation(hydrated, to: &latest)
+        publicPresentation = ["receiptId": active["receiptId"]!, "resolution": .object(latest)]
+        return .object(latest)
+    }
+    private func presentationButtons() -> [String: IndianaJSON] {
+        guard let active = current?.paywall?.object, let cached = publicPresentation,
+              active["receiptId"] == cached["receiptId"], let value = active["resolution"]?.object,
+              let loaded = cached["resolution"]?.object, loaded["id"] == value["id"], loaded["content"] == value["content"] else { return [:] }
+        return loaded["document"]?.object?["buttons"]?.object ?? [:]
+    }
+    private func responseObject() throws -> [String: IndianaJSON] { guard let response else { throw IndianaFunnelError.invalidCommand };return try JSONDecoder().decode(IndianaJSON.self, from: response).object ?? [:] }
+    func trustedPurchase(_ offered: IndianaJSON) throws -> IndianaJSON {
+        let object = try responseObject(), operation = object["purchase"]?.object?["operation"] ?? current?.paywall?.object?["operation"]
+        guard operation == offered, offered != .null else { throw IndianaFunnelError.invalidCommand };return offered
+    }
+    func trustedCheckoutURL(_ offered: String) throws -> URL {
+        let object = try responseObject(), operation = object["purchase"]?.object?["operation"] ?? current?.paywall?.object?["operation"]
+        guard operation?.object?["checkoutUrl"] == .string(offered), let url = URL(string: offered), url.scheme == "https", url.host != nil, url.user == nil, url.password == nil else { throw IndianaFunnelError.invalidCommand };return url
+    }
+    func trustedOpen(_ offered: IndianaJSON) throws -> URL {
+        guard let object = offered.object, let raw = object["url"]?.string, let url = URL(string: raw), url.scheme == "https", url.host != nil, url.user == nil, url.password == nil else { throw IndianaFunnelError.invalidCommand }
+        let instruction = current?.instruction?.object
+        let actions = presentationButtons()
+        guard instruction?["type"] == .string("open_url") && instruction?["url"] == .string(raw) && instruction?["receiptId"] == object["receiptId"] && instruction?["openIn"] == object["openIn"] || actions.values.contains(where: { $0.object?["type"] == .string("action") && $0.object?["action"]?.object?["type"] == .string("open_url") && $0.object?["action"]?.object?["url"] == .string(raw) }) else { throw IndianaFunnelError.invalidCommand };return url
+    }
+    func trustedEvent(_ name: String) throws -> String {
+        let instruction = current?.instruction?.object
+        let buttons = presentationButtons()
+        guard instruction?["type"] == .string("event") && instruction?["event"] == .string(name) || buttons.values.contains(where: { $0.object?["type"] == .string("action") && $0.object?["action"]?.object?["type"] == .string("event") && $0.object?["action"]?.object?["event"] == .string(name) }) else { throw IndianaFunnelError.invalidCommand }
+        return name
+    }
+}