@advenue/react-native 0.8.0 → 1.0.0

package/ios/vendor/AdvenueCore/Limits.swift

@@ -0,0 +1,41 @@
+import Foundation
+
+/// `clientEventSchema.name` — min 1, max 128.
+public let MAX_NAME_LENGTH = 128
+/// `propertiesSchema` — at most this many keys.
+public let MAX_PROPERTIES_KEYS = 50
+/// `propertiesSchema` — serialised length must not exceed this.
+public let MAX_PROPERTIES_BYTES = 8192
+
+/// Reasons `track()` refuses an event. Raw values match the TypeScript
+/// implementation so an `onError` context reads the same across SDKs.
+public enum TrackRejection: String, Sendable {
+  case nameEmpty = "name_empty"
+  case nameTooLong = "name_too_long"
+  case propertiesTooManyKeys = "properties_too_many_keys"
+  case propertiesTooLarge = "properties_too_large"
+  case propertiesUnserialisable = "properties_unserialisable"
+}
+
+/// Client-side enforcement of the ingest schema's budgets.
+///
+/// The server parses a batch as a whole, so an event it will reject costs an
+/// isolation pass — one failed batch POST followed by up to `batchSize`
+/// individual POSTs on a mobile radio — and the event is discarded regardless.
+/// Refusing here loses the same one event and spends nothing.
+///
+/// Values mirror `packages/shared/src/events.ts`, which is the authority.
+public func checkTrackInput(
+  name: String,
+  properties: [String: AdvenueValue]?
+) -> TrackRejection? {
+  if name.isEmpty { return .nameEmpty }
+  if name.count > MAX_NAME_LENGTH { return .nameTooLong }
+  guard let properties else { return nil }
+  if properties.count > MAX_PROPERTIES_KEYS { return .propertiesTooManyKeys }
+  guard let data = try? EventEncoding.canonicalEncoder().encode(properties) else {
+    return .propertiesUnserialisable
+  }
+  if data.count > MAX_PROPERTIES_BYTES { return .propertiesTooLarge }
+  return nil
+}

package/ios/vendor/AdvenueCore/PIIScrub.swift

@@ -0,0 +1,102 @@
+import Foundation
+
+/// M2: track properties PII scrubbing (varsayılan-açık).
+///
+/// Anahtar-adı tabanlı (e-posta/telefon/ad-soyadı çağrıştıran anahtarlar) +
+/// değer-örüntü tabanlı (e-posta/telefon regex) eşleşen değerler gönderilmeden
+/// önce kaldırılır; ham değer ağa çıkmaz. Yalnızca Foundation kullanır, böylece
+/// AdvenueCore'un Linux taşınabilirliği korunur.
+public enum PIIScrub {
+  /// Tam-eşleşme yapılan normalize anahtarlar (küçük harf, alfanümerik dışı
+  /// karakterler atılmış). Kısa anahtarlar (`ad`, `tel`) bilinçli olarak
+  /// listededir: spec'in anahtar-adı sözleşmesi bunu gerektirir.
+  private static let blockedKeys: Set<String> = [
+    "email", "emailaddress", "emailadres", "eposta", "mail",
+    "phone", "phonenumber", "mobile", "mobilenumber", "mobil",
+    "telefon", "telefonno", "tel", "telno", "gsm",
+    "firstname", "lastname", "ad", "soyad", "adsoyad", "adisoyadi",
+    "fullname", "namesurname", "isim", "isimsoyisim",
+  ]
+
+  /// Alt-dize eşleşmesi yapılan parçalar: `user_email`, `phone_number` gibi
+  /// bileşik anahtarları yakalar.
+  private static let blockedSubstrings = [
+    "email", "phone", "telefon", "soyad", "adsoyad", "firstname", "lastname",
+    "fullname",
+  ]
+
+  private static let emailPattern =
+    "[A-Z0-9._%+-]+@[A-Z0-9.-]+\\.[A-Z]{2,}"
+
+  private static func normalizeKey(_ key: String) -> String {
+    key.lowercased().filter { $0.isLetter || $0.isNumber }
+  }
+
+  static func isSensitiveKey(_ key: String) -> Bool {
+    let normalized = normalizeKey(key)
+    if blockedKeys.contains(normalized) { return true }
+    return blockedSubstrings.contains { normalized.contains($0) }
+  }
+
+  private static func matches(_ value: String, pattern: String) -> Bool {
+    guard
+      let regex = try? NSRegularExpression(
+        pattern: pattern, options: [.caseInsensitive])
+    else { return false }
+    let range = NSRange(value.startIndex..., in: value)
+    return regex.firstMatch(in: value, options: [], range: range) != nil
+  }
+
+  /// Telefon sezgiseli: çapasız alt-dize araması YOK — o yaklaşım hex hash
+  /// (`sourceUrlHash`), tarih (`2026-09-08`) ve sürüm dizgelerindeki rakam
+  /// dizilerini telefon sanıp PII olmayan özellikleri siliyordu. Değerin TÜMÜ
+  /// telefon karakterlerinden oluşmalı ve rakam sayısı E.164 aralığında
+  /// (10–15) olmalı.
+  private static func looksLikePhone(_ value: String) -> Bool {
+    let trimmed = value.trimmingCharacters(in: .whitespacesAndNewlines)
+    guard !trimmed.isEmpty else { return false }
+    let allowed = CharacterSet(charactersIn: "+0123456789 \t.-()")
+    guard trimmed.unicodeScalars.allSatisfy({ allowed.contains($0) }) else {
+      return false
+    }
+    guard let first = trimmed.first, first == "+" || first.isNumber,
+      let last = trimmed.last, last.isNumber
+    else { return false }
+    return (10...15).contains(trimmed.filter { $0.isNumber }.count)
+  }
+
+  /// Dize değer PII örüntüsü taşıyorsa true döner.
+  public static func isSensitiveValue(_ value: String) -> Bool {
+    matches(value, pattern: emailPattern) || looksLikePhone(value)
+  }
+
+  private static func scrubValue(_ value: AdvenueValue) -> AdvenueValue? {
+    switch value {
+    case .string(let s):
+      return isSensitiveValue(s) ? nil : value
+    case .array(let items):
+      return .array(items.compactMap { scrubValue($0) })
+    case .object(let dict):
+      guard let cleaned = scrub(dict) else { return nil }
+      return .object(cleaned)
+    case .int, .double, .bool, .null:
+      return value
+    }
+  }
+
+  /// PII taşıyan girdileri kaldırır. Girdi nil ise nil döner.
+  public static func scrub(
+    _ properties: [String: AdvenueValue]?
+  ) -> [String: AdvenueValue]? {
+    guard let properties else { return nil }
+    var kept: [String: AdvenueValue] = [:]
+    kept.reserveCapacity(properties.count)
+    for (key, value) in properties {
+      if isSensitiveKey(key) { continue }
+      if let cleaned = scrubValue(value) {
+        kept[key] = cleaned
+      }
+    }
+    return kept
+  }
+}

package/ios/vendor/AdvenueCore/SessionTracker.swift

@@ -0,0 +1,139 @@
+import Foundation
+
+public let SESSION_STATE_KEY = "advenue.session"
+public let DEFAULT_SESSION_WINDOW_MS: Int64 = 1_800_000  // 30 minutes
+
+/// A session lifecycle event. Values are numbers, strings and bools only.
+public struct SessionEvent: Equatable, Sendable {
+  public let name: String
+  public let properties: [String: AdvenueValue]
+}
+
+/// Persisted state. Field names match the TypeScript shape exactly — the RN
+/// inversion reads state this SDK wrote and vice versa, and a renamed field
+/// would silently restart every device's session numbering.
+struct SessionState: Codable {
+  var sessionId: String
+  var sessionNumber: Int
+  var lastBackgroundAt: Int64?
+  var subSessionCount: Int
+  var activeStart: Int64?
+  var firstForegroundAt: Int64
+  var timeSpentMs: Int64
+}
+
+/// Platform-agnostic session state machine. Pure: it persists state and
+/// returns the events to emit; enqueueing is the caller's job.
+public final class SessionTracker {
+  private var cached: SessionState?
+  private let store: KeyValueStore
+  private let clock: Clock
+  private let windowMs: Int64
+  private let uuid: UUIDSource
+
+  public init(store: KeyValueStore, clock: Clock, windowMs: Int64, uuid: UUIDSource) {
+    self.store = store
+    self.clock = clock
+    self.windowMs = windowMs
+    self.uuid = uuid
+  }
+
+  /// Drops the in-memory cache so a wiped store cannot be resurrected by a
+  /// later lifecycle call (GDPR erasure).
+  public func reset() { cached = nil }
+
+  private func load() -> SessionState? {
+    if let cached { return cached }
+    guard let raw = store.string(forKey: SESSION_STATE_KEY),
+      let data = raw.data(using: .utf8),
+      let parsed = try? JSONDecoder().decode(SessionState.self, from: data)
+    else { return nil }
+    cached = parsed
+    return parsed
+  }
+
+  private func save(_ state: SessionState) {
+    cached = state
+    guard let data = try? EventEncoding.canonicalEncoder().encode(state) else { return }
+    store.set(String(decoding: data, as: UTF8.self), forKey: SESSION_STATE_KEY)
+  }
+
+  /// Foreground transition, including cold start. Returns the events to emit:
+  /// none for a sub-session, one `session_start` for a new session, or a
+  /// synthetic `session_end` FOLLOWED BY the start when the previous session
+  /// was still open — the OS killed the app before it could background. The
+  /// order is load-bearing: a consumer must never see two sessions open.
+  public func handleForeground() -> [SessionEvent] {
+    let state = load()
+    let now = clock.nowMs()
+    let gap: Int64? = state?.lastBackgroundAt.map { now - $0 }
+
+    if state == nil || gap == nil || gap! >= windowMs {
+      let sessionNumber = (state?.sessionNumber ?? 0) + 1
+      let sessionId = uuid.next()
+      save(
+        SessionState(
+          sessionId: sessionId, sessionNumber: sessionNumber, lastBackgroundAt: nil,
+          subSessionCount: 1, activeStart: now, firstForegroundAt: now, timeSpentMs: 0))
+
+      let start = SessionEvent(
+        name: "session_start",
+        properties: [
+          "sessionId": .string(sessionId),
+          "sessionNumber": .int(sessionNumber),
+          "subSession": .int(1),
+          "isFirstSession": .bool(sessionNumber == 1),
+          "timeSinceLastSessionMs": .int(Int(gap ?? 0)),
+        ])
+
+      if let prior = state, let activeStart = prior.activeStart {
+        let killTime = prior.lastBackgroundAt ?? now
+        let activeMs = max(0, killTime - activeStart)
+        let end = SessionEvent(
+          name: "session_end",
+          properties: [
+            "sessionId": .string(prior.sessionId),
+            "sessionNumber": .int(prior.sessionNumber),
+            "subSession": .int(prior.subSessionCount),
+            "activeMs": .int(Int(activeMs)),
+            "timeSpentMs": .int(Int(prior.timeSpentMs + activeMs)),
+            "sessionLengthMs": .int(Int(max(0, killTime - prior.firstForegroundAt))),
+            "synthetic": .bool(true),
+          ])
+        return [end, start]
+      }
+      return [start]
+    }
+
+    var updated = state!
+    updated.subSessionCount += 1
+    updated.activeStart = now
+    save(updated)
+    return []
+  }
+
+  /// Background transition. Emits a `session_end` carrying this sub-session's
+  /// stretch (`activeMs`), the session's cumulative active time
+  /// (`timeSpentMs`) and its wall-clock span (`sessionLengthMs`) — three
+  /// different numbers a port is likely to collapse into one.
+  public func handleBackground() -> SessionEvent? {
+    guard var state = load(), let activeStart = state.activeStart else { return nil }
+    let now = clock.nowMs()
+    let activeMs = max(0, now - activeStart)
+    let timeSpentMs = state.timeSpentMs + activeMs
+    state.lastBackgroundAt = now
+    state.activeStart = nil
+    state.timeSpentMs = timeSpentMs
+    save(state)
+    return SessionEvent(
+      name: "session_end",
+      properties: [
+        "sessionId": .string(state.sessionId),
+        "sessionNumber": .int(state.sessionNumber),
+        "subSession": .int(state.subSessionCount),
+        "activeMs": .int(Int(activeMs)),
+        "timeSpentMs": .int(Int(timeSpentMs)),
+        "sessionLengthMs": .int(Int(max(0, now - state.firstForegroundAt))),
+      ])
+  }
+}

package/ios/vendor/AdvenueCore/SkanConfig.swift

@@ -0,0 +1,76 @@
+import Foundation
+
+/// The conversion-value config as the server serves it, with the version the
+/// server uses to tell which config produced a reported value.
+public struct RemoteSkanConfig: Equatable, Sendable {
+  public let version: Int
+  public let rules: ConversionValueConfig
+  public let etag: String?
+
+  public init(version: Int, rules: ConversionValueConfig, etag: String? = nil) {
+    self.version = version
+    self.rules = rules
+    self.etag = etag
+  }
+}
+
+public enum SkanConfigResult: Sendable {
+  case fetched(RemoteSkanConfig)
+  /// The server answered 304: whatever is cached is still current.
+  case notModified
+}
+
+public protocol SkanConfigSource: Sendable {
+  func fetch(etag: String?) async throws -> SkanConfigResult
+}
+
+public let SKAN_CONFIG_KEY = "advenue.skan.config"
+
+/// Decides which config to use, given what the server said and what is cached.
+///
+/// The rules are about staying measurable rather than staying current:
+///
+/// - A **304** or a **failure** keeps the cached config. A device on a flaky
+///   network must not lose SKAN entirely; a config from last week measures far
+///   more than no config at all.
+/// - A fetched config that does **not validate** is refused and the cache kept.
+///   A bad config pushed to production would otherwise brick measurement on
+///   every device at once, which is the failure mode a remote config exists to
+///   avoid rather than create.
+/// - Only when there is no cache and no valid fetch does the app-supplied
+///   config apply, which is why it stays in `AdvenueConfig` as an offline
+///   default rather than being removed.
+public func chooseSkanConfig(
+  fetched: SkanConfigResult?,
+  cached: RemoteSkanConfig?,
+  fallback: ConversionValueConfig?
+) -> RemoteSkanConfig? {
+  if case .fetched(let remote) = fetched, (try? ConversionValueMapper(remote.rules)) != nil {
+    return remote
+  }
+  if let cached { return cached }
+  guard let fallback, (try? ConversionValueMapper(fallback)) != nil else { return nil }
+  // Version 0 marks "not from the server", which is what the server reads it as.
+  return RemoteSkanConfig(version: 0, rules: fallback)
+}
+
+
+extension RemoteSkanConfig: Codable {
+  private enum CodingKeys: String, CodingKey { case version, rules, etag }
+}
+
+/// Reads and writes the cached config. Persisted so a launch with no network
+/// still measures — the alternative is that every offline cold start silently
+/// stops reporting conversion values.
+public enum SkanConfigCache {
+  public static func load(_ store: KeyValueStore) -> RemoteSkanConfig? {
+    guard let raw = store.string(forKey: SKAN_CONFIG_KEY), let data = raw.data(using: .utf8)
+    else { return nil }
+    return try? JSONDecoder().decode(RemoteSkanConfig.self, from: data)
+  }
+
+  public static func save(_ config: RemoteSkanConfig, to store: KeyValueStore) {
+    guard let data = try? EventEncoding.canonicalEncoder().encode(config) else { return }
+    store.set(String(decoding: data, as: UTF8.self), forKey: SKAN_CONFIG_KEY)
+  }
+}

package/ios/vendor/AdvenueCore/SkanReporter.swift

@@ -0,0 +1,25 @@
+import Foundation
+
+/// What the core needs from SKAdNetwork, and no more.
+///
+/// Declared here so `AdvenueCore` keeps importing only Foundation while still
+/// owning the decision of *when* to report — that decision is what the tests
+/// can settle, and the Apple call is what they cannot.
+public protocol SkanReporter: Sendable {
+  /// Registers the install for attribution. Apple wants this at first launch;
+  /// a late call loses the attribution window.
+  func register()
+
+  /// Reports a conversion value. Throws when the platform refuses it, and the
+  /// caller must NOT confirm a throw — a device that recorded a value it never
+  /// sent would refuse to send it again, and that window would report nothing
+  /// for the rest of its life.
+  func update(fine: Int, coarse: CoarseValue, lockWindow: Bool) async throws
+}
+
+/// A reporter that does nothing, for platforms and configurations with no SKAN.
+public struct NoopSkanReporter: SkanReporter {
+  public init() {}
+  public func register() {}
+  public func update(fine: Int, coarse: CoarseValue, lockWindow: Bool) async throws {}
+}

package/ios/vendor/AdvenueCore/SkanState.swift

@@ -0,0 +1,258 @@
+import Foundation
+
+public let DAY_MS: Int64 = 86_400_000
+
+/// SKAdNetwork 4 measures three windows from first launch. Boundaries are
+/// Apple's and inclusive at the top: `[0,2d] → 1`, `(2d,7d] → 2`,
+/// `(7d,35d] → 3`, beyond that nothing is measurable.
+///
+/// A device whose clock is behind first launch produces a negative age and
+/// reads as window 1. Degrade, never throw: this runs on a path the SDK
+/// swallows, so an exception here would silently stop measurement instead of
+/// reporting anything.
+public func deriveWindowIndex(firstLaunchAt: Int64, nowMs: Int64) -> Int? {
+  let age = nowMs - firstLaunchAt
+  if age <= 2 * DAY_MS { return 1 }
+  if age <= 7 * DAY_MS { return 2 }
+  if age <= 35 * DAY_MS { return 3 }
+  return nil
+}
+
+public func skanStateKey(installationId: String) -> String {
+  "advenue.skan.state.\(installationId)"
+}
+
+/// One measurement window's accumulation.
+public struct WindowState: Codable, Equatable, Sendable {
+  public var seenEvents: [String] = []
+  /// Canonical micros. A string, because money must not go through a Double.
+  public var revenueMicros: String = "0"
+  public var lastFine: Int?
+  public var lastCoarse: CoarseValue?
+  public var locked: Bool = false
+  /// Write-ahead intent: what we are about to tell Apple. Persisted BEFORE the
+  /// call so a crash between the two cannot leave the device believing it
+  /// reported a value it never sent.
+  public var pendingFine: Int?
+  public var pendingCoarse: CoarseValue?
+
+  public init() {}
+}
+
+/// Coarse buckets are ordered, and the gate below compares them as an order
+/// rather than for equality — a move from low to medium is progress, the
+/// reverse is not.
+func coarseOrder(_ value: CoarseValue) -> Int {
+  switch value {
+  case .low: return 0
+  case .medium: return 1
+  case .high: return 2
+  }
+}
+
+/// The persisted blob. **Field names are frozen**: the RN inversion has to read
+/// what TypeScript wrote, and a rename silently restarts every device's SKAN
+/// measurement — which looks like a fleet-wide drop in postback quality with no
+/// error anywhere.
+public struct SkanMeasurementState: Codable, Equatable, Sendable {
+  public var v: Int = 2
+  public var firstLaunchAt: Int64
+  public var configVersion: Int = 0
+  public var windows: [String: WindowState]
+
+  public init(firstLaunchAt: Int64) {
+    self.firstLaunchAt = firstLaunchAt
+    self.windows = ["w1": WindowState(), "w2": WindowState(), "w3": WindowState()]
+  }
+}
+
+/// What the platform layer should tell Apple, or nil when there is nothing
+/// worth saying.
+public struct SkanUpdate: Equatable, Sendable {
+  public let fineValue: Int
+  public let coarseValue: CoarseValue
+  public let windowIndex: Int
+  /// True on the last update of a window: Apple stops accepting changes and
+  /// sends the postback sooner.
+  public let lockWindow: Bool
+}
+
+/// The client half of SKAN 4: accumulate into the current window, recompute,
+/// and decide whether an update is worth making.
+///
+/// Confined to the engine's thread like every other piece of state.
+public final class SkanStateMachine {
+  private let store: KeyValueStore
+  private let clock: Clock
+  private let installationId: String
+  private let mapper: ConversionValueMapper
+  private let currency: String?
+  private var state: SkanMeasurementState
+
+  public init(
+    store: KeyValueStore,
+    clock: Clock,
+    installationId: String,
+    mapper: ConversionValueMapper,
+    currency: String? = nil,
+    configVersion: Int = 0
+  ) {
+    self.store = store
+    self.clock = clock
+    self.installationId = installationId
+    self.mapper = mapper
+    self.currency = currency
+    self.state = Self.load(store, key: skanStateKey(installationId: installationId))
+      ?? SkanMeasurementState(firstLaunchAt: clock.nowMs())
+    // Recorded so the server can tell which config produced a reported value.
+    // A schema change mid-window otherwise looks like a device behaving oddly.
+    self.state.configVersion = configVersion
+    persist()
+  }
+
+  /// Records an event and returns the update to make, or nil.
+  ///
+  /// Nil for three distinct reasons, all of which matter: the install is past
+  /// the last window, the window is locked, or the computed value has not
+  /// changed. That last one is not an optimisation — SKAN updates are
+  /// rate-limited by the system and each one restarts a timer, so a no-op
+  /// update costs the advertiser measurement resolution.
+  @discardableResult
+  public func record(
+    event: String?, revenueMicros: String? = nil, revenueCurrency: String? = nil
+  ) -> SkanUpdate? {
+    guard let index = deriveWindowIndex(firstLaunchAt: state.firstLaunchAt, nowMs: clock.nowMs())
+    else { return nil }
+    let key = "w\(index)"
+    var window = state.windows[key] ?? WindowState()
+    if window.locked { return nil }
+
+    if let event, !window.seenEvents.contains(event) { window.seenEvents.append(event) }
+    if let revenueMicros, isCanonicalMicros(revenueMicros) {
+      // Revenue accumulates within a window and does not carry into the next:
+      // each SKAN window measures its own period.
+      if window.revenueMicros == "0" || revenueCurrency == currency {
+        window.revenueMicros = addMicros(window.revenueMicros, revenueMicros)
+      }
+    }
+
+    let computed = mapper.compute(
+      MeasurementState(
+        events: window.seenEvents,
+        revenueMicros: window.revenueMicros,
+        revenueCurrency: revenueCurrency ?? currency))
+
+    // Monotonic within the window, and the two baselines differ on purpose.
+    //
+    // Fine baseline is **0**, not -1: a computed fine of 0 is the mapper's "no
+    // rule matched" default, so on its own it is not news and must not spend a
+    // rate-limited update. Fine is also only meaningful in window 1 — after
+    // that Apple ignores it for v4 ads.
+    //
+    // Coarse baseline is **-1**, so the first coarse activation fires even at
+    // `low`. That is what keeps windows 2 and 3 reporting at all; gating them
+    // on fine alone silently no-ops them.
+    let fineIncreased = index == 1 && computed.fineValue > (window.lastFine ?? 0)
+    let coarseIncreased =
+      coarseOrder(computed.coarseValue) > (window.lastCoarse.map(coarseOrder) ?? -1)
+
+    guard fineIncreased || coarseIncreased else {
+      state.windows[key] = window
+      persist()
+      return nil
+    }
+
+    // After window 1, send window 1's FROZEN fine: Apple ignores it on v4 ads,
+    // and a valid value still serves v3-signed ones.
+    let fineToSend =
+      index == 1 ? computed.fineValue : (state.windows["w1"]?.lastFine ?? 0)
+
+    window.pendingFine = index == 1 ? computed.fineValue : nil
+    window.pendingCoarse = computed.coarseValue
+    state.windows[key] = window
+    persist()
+
+    return SkanUpdate(
+      fineValue: fineToSend, coarseValue: computed.coarseValue,
+      windowIndex: index, lockWindow: false)
+  }
+
+  /// Commits an update the platform layer actually delivered.
+  ///
+  /// Separate from `record` because the Apple call can fail, and a device that
+  /// recorded a value it never sent would refuse to send it again — the window
+  /// would report nothing for the rest of its life.
+  public func confirm(_ update: SkanUpdate) {
+    let key = "w\(update.windowIndex)"
+    guard var window = state.windows[key] else { return }
+    if update.windowIndex == 1, let pending = window.pendingFine { window.lastFine = pending }
+    if let pending = window.pendingCoarse { window.lastCoarse = pending }
+    if update.lockWindow { window.locked = true }
+    window.pendingFine = nil
+    window.pendingCoarse = nil
+    state.windows[key] = window
+    persist()
+  }
+
+  /// Discards an intent the platform layer could not deliver, so the next
+  /// qualifying event tries again.
+  public func abandon(_ update: SkanUpdate) {
+    let key = "w\(update.windowIndex)"
+    guard var window = state.windows[key] else { return }
+    window.pendingFine = nil
+    window.pendingCoarse = nil
+    state.windows[key] = window
+    persist()
+  }
+
+  /// Closes a window to further updates. Apple then stops accepting changes, so
+  /// sending after this is an update the system silently discards while the SDK
+  /// believes it landed.
+  public func lock(window index: Int) {
+    let key = "w\(index)"
+    guard var window = state.windows[key] else { return }
+    window.locked = true
+    state.windows[key] = window
+    persist()
+  }
+
+  public func snapshot() -> SkanMeasurementState { state }
+
+  private func persist() {
+    guard let data = try? EventEncoding.canonicalEncoder().encode(state) else { return }
+    store.set(
+      String(decoding: data, as: UTF8.self),
+      forKey: skanStateKey(installationId: installationId))
+  }
+
+  /// A corrupt blob loads as fresh state rather than throwing — the same rule
+  /// the event queue follows, and for the same reason: bricking measurement on
+  /// every launch is worse than losing one device's accumulation.
+  private static func load(_ store: KeyValueStore, key: String) -> SkanMeasurementState? {
+    guard let raw = store.string(forKey: key), let data = raw.data(using: .utf8) else {
+      return nil
+    }
+    return try? JSONDecoder().decode(SkanMeasurementState.self, from: data)
+  }
+}
+
+/// Adds two canonical non-negative base-10 micro amounts without a bignum and
+/// without a Double, which would lose exactness above 2^53 micros.
+func addMicros(_ lhs: String, _ rhs: String) -> String {
+  var carry = 0
+  var out: [Character] = []
+  let a = Array(lhs.reversed()), b = Array(rhs.reversed())
+  for i in 0..<max(a.count, b.count) {
+    let x = i < a.count ? Int(String(a[i])) ?? 0 : 0
+    let y = i < b.count ? Int(String(b[i])) ?? 0 : 0
+    let sum = x + y + carry
+    out.append(Character(String(sum % 10)))
+    carry = sum / 10
+  }
+  if carry > 0 { out.append(Character(String(carry))) }
+  let result = String(out.reversed())
+  // Strip leading zeros to keep the value canonical, which the comparison and
+  // the server's schema both require.
+  let trimmed = result.drop(while: { $0 == "0" })
+  return trimmed.isEmpty ? "0" : String(trimmed)
+}