feat(network): add NetworkPolicyContributor/Aggregator for multi-consumer policy composition

Currently MapStore is the sole writer of NetworkGateway state via setEnabled+setPolicy. As soon as a second consumer (e.g. OSM PMTiles offline pre-cache download) wants its own allowlist+rate limit, both consumers fight for the global state and last writer wins.

Introduce a contributor/aggregator pattern in :network:

* NetworkPolicyContributor exposes a StateFlow<NetworkPolicyContribution> with stable id, allowing features to publish their current 'what hosts I need' view reactively. Inactive == not contributing.

* NetworkPolicyAggregator (Singleton) combines every contributor and pushes the union policy onto the gateway. Kill switch armed iff any contributor active; allowedHosts = set union; perHostRateLimit/Window = MAX (so a bursty contributor isn't capped by a quieter peer).

* Empty-contributors degenerate case is explicit: combine() over an empty Iterable never emits, so the aggregator short-circuits and leaves the gateway at its deny-all default (no observable signal otherwise).

* Policy is published BEFORE the kill switch on every emission so the interceptor chain sees the right allowlist on the very first request after a 0->1 transition and stays consistent on a 1->0 transition.

Tests cover: all-inactive, single-active, two-disjoint, two-overlapping, MAX-window selection, partial hot-swap, full hot-swap, and zero-contributors edge case. Uses FakeNetworkGateway + TestScope + a tiny MutableStateFlow-backed fake contributor — no Hilt in tests, keeping :network free of DI infrastructure.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: adsamcik

network/src/main/java/com/adsamcik/tracker/network/NetworkPolicyAggregator.kt

@@ -0,0 +1,123 @@
+package com.adsamcik.tracker.network
+
+import kotlinx.coroutines.CoroutineScope
+import kotlinx.coroutines.Job
+import kotlinx.coroutines.flow.combine
+import kotlinx.coroutines.launch
+import javax.inject.Inject
+import javax.inject.Singleton
+
+/**
+ * Single owner of [NetworkGateway.setEnabled] + [NetworkGateway.setPolicy].
+ *
+ * Subscribes to every registered [NetworkPolicyContributor] and pushes the
+ * union of their active contributions onto the gateway. Construction launches
+ * a coroutine on the supplied [scope] that lives for the entire process — the
+ * aggregator is intended to be a `@Singleton`, eagerly instantiated from
+ * `Application.onCreate` so the gateway is always in a consistent state by
+ * the time any feature surfaces UI.
+ *
+ * # Composition semantics
+ *
+ *  - **Kill switch.** The gateway is enabled iff at least one contributor is
+ *    [NetworkPolicyContribution.Active]. With zero active contributors the
+ *    kill switch flips OFF and the gateway publishes [NetworkPolicy.EMPTY],
+ *    which fail-closes every subsequent request. This matches the privacy
+ *    contract: "opt-in is the only safe default".
+ *
+ *  - **Allowed hosts.** Union of every active contributor's
+ *    [NetworkPolicyContribution.Active.allowedHosts]. Overlapping hosts are
+ *    deduplicated (set semantics).
+ *
+ *  - **Rate limits.** A single per-host rate limit applies to every host in
+ *    the effective policy. When multiple contributors are active we take the
+ *    MAX of their requested limits — the alternative (MIN) would let a quiet
+ *    contributor throttle a bursty one even on hosts the bursty contributor
+ *    is the sole consumer of. The same logic applies to
+ *    [NetworkPolicyContribution.Active.perHostRateWindowMs] (MAX window =
+ *    most permissive). Per-host-within-policy granularity is a future
+ *    extension that requires [NetworkPolicy] to grow a `Map<String, Int>`.
+ *
+ * # Zero-contributors degenerate case
+ *
+ * Hilt's `@Multibinds` may resolve to an empty set if no module contributes.
+ * In that case the constructor short-circuits: no collector is launched and
+ * the gateway is left at its initial deny-all state. This is safe (no traffic
+ * flows) and the empty-set path is covered by tests so a future refactor
+ * that accidentally unbinds every contributor still surfaces clearly.
+ *
+ * # Why a class, not an init-time helper
+ *
+ * Holding the collector job in [collectorJob] gives tests a synchronous
+ * signal that the subscription is live ([isCollecting]) and lets future
+ * shutdown paths cancel cleanly without yanking the whole [scope].
+ *
+ * @param gateway The singleton [NetworkGateway] to drive. Constructor-injected
+ *   so tests can swap a [FakeNetworkGateway].
+ * @param contributors Every [NetworkPolicyContributor] currently registered.
+ *   Hilt's `@JvmSuppressWildcards` annotation on the call site keeps the
+ *   `Set<NetworkPolicyContributor>` type stable across Kotlin/Java boundaries
+ *   for multibindings; consumers in `:network` (tests) can pass any `Set`.
+ * @param scope Long-lived coroutine scope (typically `@ApplicationScope`)
+ *   that owns the combine collector for the process lifetime.
+ */
+@Singleton
+class NetworkPolicyAggregator @Inject constructor(
+	private val gateway: NetworkGateway,
+	private val contributors: Set<@JvmSuppressWildcards NetworkPolicyContributor>,
+	private val scope: CoroutineScope,
+) {
+
+	private val collectorJob: Job? = startCollector()
+
+	/**
+	 * `true` once the combine collector is running. Always `false` when zero
+	 * contributors are registered (the degenerate, safe path). Useful in
+	 * tests that need to assert the aggregator wired up at all without
+	 * waiting on a [NetworkGateway] state change.
+	 */
+	val isCollecting: Boolean
+		get() = collectorJob?.isActive == true
+
+	private fun startCollector(): Job? {
+		if (contributors.isEmpty()) {
+			// kotlinx.coroutines.flow.combine over an empty Iterable never
+			// emits, so launching a collector would leave the gateway at its
+			// initial deny-all state with no observable signal. Make the
+			// no-contributor case explicit instead of relying on combine's
+			// silent never-emit behaviour. Gateway stays disabled / EMPTY by
+			// its own default — exactly what we'd publish anyway.
+			return null
+		}
+		val flows = contributors.map { it.contribution }
+		return scope.launch {
+			combine(flows) { snapshot -> aggregate(snapshot.toList()) }
+				.collect { (enabled, policy) ->
+					// Publish policy BEFORE arming the kill switch so the
+					// interceptor chain sees the right allowlist on the very
+					// first request that flows after a 0→1 transition.
+					// Conversely on a 1→0 transition publishing policy first
+					// (now EMPTY) means in-flight requests that race the
+					// kill switch are also rejected by the allowlist gate —
+					// belt-and-braces.
+					gateway.setPolicy(policy)
+					gateway.setEnabled(enabled)
+				}
+		}
+	}
+
+	private fun aggregate(
+		contributions: List<NetworkPolicyContribution>,
+	): Pair<Boolean, NetworkPolicy> {
+		val active = contributions.filterIsInstance<NetworkPolicyContribution.Active>()
+		if (active.isEmpty()) return false to NetworkPolicy.EMPTY
+		val allHosts = active.flatMapTo(HashSet()) { it.allowedHosts }
+		val maxLimit = active.maxOf { it.perHostRateLimit }
+		val maxWindow = active.maxOf { it.perHostRateWindowMs }
+		return true to NetworkPolicy(
+			allowedHosts = allHosts,
+			perHostRateLimit = maxLimit,
+			perHostRateWindowMs = maxWindow,
+		)
+	}
+}

network/src/main/java/com/adsamcik/tracker/network/NetworkPolicyContributor.kt

@@ -0,0 +1,103 @@
+package com.adsamcik.tracker.network
+
+import kotlinx.coroutines.flow.StateFlow
+
+/**
+ * A feature-scoped contributor that publishes its current view of "what hosts
+ * I need network access to, with what rate limits". The
+ * [NetworkPolicyAggregator] combines every contributor's [contribution] into
+ * the single effective [NetworkPolicy] driven onto the [NetworkGateway].
+ *
+ * # Why contributors instead of direct gateway calls
+ *
+ * Historically `MapStore` was the SOLE writer of [NetworkGateway] state via
+ * [NetworkGateway.setEnabled] + [NetworkGateway.setPolicy]. Any second
+ * consumer (e.g. an OSM PMTiles offline pre-cache download) wanting its own
+ * allowlist + rate limit would fight `MapStore` for the global state — last
+ * writer wins, the loser's hosts get silently locked out.
+ *
+ * Contributors solve this:
+ *
+ *  - Every feature that needs network access implements
+ *    [NetworkPolicyContributor] and Hilt-registers itself via
+ *    `@IntoSet`.
+ *  - When the feature is "off" (user toggle disabled, download finished),
+ *    the contributor emits [NetworkPolicyContribution.Inactive] —
+ *    contributing nothing to the union.
+ *  - When the feature is "on", it emits a
+ *    [NetworkPolicyContribution.Active] carrying its hosts + per-host limits.
+ *  - The aggregator unions every active contribution into a single
+ *    [NetworkPolicy] and arms the kill switch iff at least one contributor
+ *    is active.
+ *
+ * Direct [NetworkGateway.setEnabled] / [NetworkGateway.setPolicy] calls from
+ * feature code are now an anti-pattern — they will be silently overwritten on
+ * the next contributor emission.
+ *
+ * # Threading
+ *
+ * [contribution] is a [StateFlow]; the aggregator subscribes once at app
+ * startup and stays subscribed for process lifetime. Implementations are
+ * responsible for hoisting their preference / state flows onto a stable
+ * [StateFlow] (typically via `stateIn(scope, SharingStarted.Eagerly, …)`)
+ * so the aggregator always has a value to combine without suspending.
+ */
+interface NetworkPolicyContributor {
+	/**
+	 * Stable identifier (e.g. `"map-tiles"`, `"osm-download"`). Used for
+	 * debugging, audit logs, and future per-contributor diagnostics. NOT
+	 * surfaced in UI — pick something machine-readable and stable across
+	 * releases.
+	 */
+	val id: String
+
+	/**
+	 * Reactive contribution. Each emission is this contributor's current
+	 * snapshot of "what hosts I need + with what rate limits". When this
+	 * contributor is off (e.g. user toggle disabled, download finished),
+	 * emit [NetworkPolicyContribution.Inactive].
+	 *
+	 * The aggregator re-derives the effective policy on every emission, so
+	 * implementations should debounce or coalesce upstream noise themselves
+	 * if relevant (preferences typically dedupe via `distinctUntilChanged`
+	 * already).
+	 */
+	val contribution: StateFlow<NetworkPolicyContribution>
+}
+
+/**
+ * One contributor's snapshot of "what should the gateway allow on my behalf
+ * right now". Combined across every registered [NetworkPolicyContributor] by
+ * [NetworkPolicyAggregator] into the effective [NetworkPolicy].
+ */
+sealed interface NetworkPolicyContribution {
+	/**
+	 * This contributor is currently OFF — it contributes no hosts and does
+	 * not vote to arm the gateway. If every contributor is [Inactive] the
+	 * aggregator disables the kill switch and publishes [NetworkPolicy.EMPTY].
+	 */
+	data object Inactive : NetworkPolicyContribution
+
+	/**
+	 * This contributor is currently ON — the gateway must allow these hosts
+	 * and the kill switch must be armed.
+	 *
+	 * @property allowedHosts Exact hosts (lower-case, trimmed by
+	 *   [NetworkPolicy]) this contributor requires. Subdomain wildcards are
+	 *   NOT supported; list every concrete host.
+	 * @property perHostRateLimit Maximum requests per host per
+	 *   [perHostRateWindowMs]. When multiple contributors are active the
+	 *   aggregator currently takes the MAX (per the design note in the
+	 *   coupling refactor) so a contributor with bursty needs (e.g. an
+	 *   OSM PMTiles download) isn't bottlenecked by a quieter contributor
+	 *   sharing the same effective policy. Per-host fine-grained limits
+	 *   are a deferred extension to [NetworkPolicy].
+	 * @property perHostRateWindowMs The rate-limit window in milliseconds.
+	 *   Defaults to [NetworkPolicy.DEFAULT_RATE_WINDOW_MS] (one minute).
+	 */
+	data class Active(
+		val allowedHosts: Set<String>,
+		val perHostRateLimit: Int = NetworkPolicy.DEFAULT_RATE_LIMIT,
+		val perHostRateWindowMs: Long = NetworkPolicy.DEFAULT_RATE_WINDOW_MS,
+	) : NetworkPolicyContribution
+}