K2GO-395 feat(networkpolicy): enforce cost gate in ContentAdmission; bank-before-gate for ZIM

Resolves ADR-395 sec.10. Gating only the UI commit point was not defensive: the
wishlist is a durable queue drained by an ungated background pass, so banked
orders (incl. the wizard-bank path) could download on metered data with no consent.

- New NetworkCostAdmission (networkpolicy/data): the single classify+consent+policy
  decision, used by both the UI gate and the headless admission.
- ContentAdmission.canStart now defers on metered-without-consent, so the ZIM,
  Books and Kolibri drains all HOLD a banked order -- one choke, three streams, no
  per-provisioner edit, no new persistent state (a held order stays banked).
- startZimDownload banks the wishlist BEFORE the gate and gates only the drain, so
  a declined/offline order is queued, not lost; ZimConfirmFragment calls it directly.
- MeteredNetworkObserver.start is now truly idempotent (started guard).

Fixes the two-pass review findings (cart loss on offline/decline; false idempotent
claim). Build + networkpolicy unit tests green.

Author: luisguzman-adfa

controller/app/src/main/java/org/appdevforall/k2go/networkpolicy/data/NetworkCostAdmission.java

@@ -0,0 +1,42 @@
+package org.appdevforall.k2go.networkpolicy.data;
+
+import android.content.Context;
+
+import androidx.annotation.NonNull;
+
+import org.appdevforall.k2go.networkpolicy.domain.NetworkPolicy;
+import org.appdevforall.k2go.networkpolicy.domain.NetworkPolicyDecision;
+
+/**
+ * The one headless "may a heavy transfer start now, cost-wise?" decision (ADR-395).
+ *
+ * <p>It is the single source of the classify + consent + policy glue, used by both
+ * the UI gate ({@code NetworkPolicyGate}, which needs the full decision to choose
+ * dialog vs snackbar) and the content-stream admission ({@code ContentAdmission},
+ * which needs only the boolean). Data-layer, so the system-side admission can call
+ * it without depending on presentation.
+ */
+public final class NetworkCostAdmission {
+
+    private NetworkCostAdmission() {}
+
+    private static final NetworkPolicy POLICY = new NetworkPolicy();
+
+    /** The full decision for the active default network and the current session consent. */
+    @NonNull
+    public static NetworkPolicyDecision decideNow(@NonNull Context ctx) {
+        return POLICY.decideHeavyStart(
+                AndroidNetworkClassifier.classify(ctx),
+                SessionMeteredConsentStore.get().isGranted());
+    }
+
+    /**
+     * True when a heavy transfer may start now on cost grounds (unmetered, or the
+     * user consented this session). False means HOLD: leave the order banked, a
+     * later pass takes it once the network is free or consent is given -- the same
+     * "deferred is not a failure" contract the other admission checks use.
+     */
+    public static boolean allowsHeavyStartNow(@NonNull Context ctx) {
+        return decideNow(ctx) == NetworkPolicyDecision.ALLOW;
+    }
+}

controller/app/src/main/java/org/appdevforall/k2go/networkpolicy/presentation/MeteredNetworkObserver.java

@@ -42,9 +42,12 @@ public final class MeteredNetworkObserver {
     private MeteredNetworkObserver() {}
 
     private static NetworkClass last = null;
+    private static boolean started = false;
 
     /** Idempotent; call once from Application.onCreate on the main thread. */
     public static void start(@NonNull Application app) {
+        if (started) return;   // guard: a second call must not add a second observeForever
+        started = true;
         ensureChannel(app);
         last = AndroidNetworkClassifier.classify(app);
         // observeForever keeps NetworkStateLiveData active for the process lifetime,

controller/app/src/main/java/org/appdevforall/k2go/networkpolicy/presentation/NetworkPolicyGate.java

@@ -6,43 +6,35 @@
 import androidx.annotation.NonNull;
 
 import org.appdevforall.k2go.R;
-import org.appdevforall.k2go.networkpolicy.data.AndroidNetworkClassifier;
+import org.appdevforall.k2go.networkpolicy.data.NetworkCostAdmission;
 import org.appdevforall.k2go.networkpolicy.data.SessionMeteredConsentStore;
-import org.appdevforall.k2go.networkpolicy.domain.MeteredConsentStore;
-import org.appdevforall.k2go.networkpolicy.domain.NetworkClass;
-import org.appdevforall.k2go.networkpolicy.domain.NetworkPolicy;
-import org.appdevforall.k2go.networkpolicy.domain.NetworkPolicyDecision;
 import org.appdevforall.k2go.ui.dialog.BrandDialog;
 import org.appdevforall.k2go.util.Snackbars;
 
 /**
- * The single consult point before any heavy download starts (ADR-395). A caller
- * wraps its existing start call:
+ * The user-facing PROMPT for a costed start (ADR-395). A commit point (a Download
+ * button) wraps its start so the user is asked before spending metered data:
  *
  * <pre>NetworkPolicyGate.guardHeavyStart(activity, () -&gt; a.startZimDownload());</pre>
  *
  * <p>Stateless, like {@code OpReturnNavigator}: it owns no "is metered" flag. It
- * reads the live class off {@link AndroidNetworkClassifier} and the session
- * consent off {@link SessionMeteredConsentStore}, applies the pure
- * {@link NetworkPolicy}, and either proceeds, asks, or blocks.
+ * reads the decision from {@link NetworkCostAdmission} (the one classify + consent
+ * + policy source) and either proceeds, asks, or reports offline.
  *
- * <p>It gates the START only. It does NOT control a transfer already in flight --
- * the content bytes are pulled by the in-proot server over the device default
- * network, which Android gives the app no handle to throttle (ADR-395). Callers
- * put this at the user's commit point (the Download button), never on the
- * background drain that re-hands an already-authorized wishlist.
+ * <p>This gate is only the PROMPT. The actual hold is enforced headless in
+ * {@code ContentAdmission} (via {@link NetworkCostAdmission}), which every content
+ * drain already consults -- so a banked order never starts on metered data without
+ * consent even if it was never routed through a commit point (the wizard-bank path,
+ * a background re-drain). Banking must therefore happen BEFORE this gate: an order
+ * declined or offline here stays queued and drains once the network is free or
+ * consent is given, rather than being lost (ADR-395 sec.10).
  */
 public final class NetworkPolicyGate {
 
     private NetworkPolicyGate() {}
 
-    private static final NetworkPolicy POLICY = new NetworkPolicy();
-
     public static void guardHeavyStart(@NonNull Activity activity, @NonNull Runnable onProceed) {
-        MeteredConsentStore consent = SessionMeteredConsentStore.get();
-        NetworkClass net = AndroidNetworkClassifier.classify(activity);
-        NetworkPolicyDecision decision = POLICY.decideHeavyStart(net, consent.isGranted());
-        switch (decision) {
+        switch (NetworkCostAdmission.decideNow(activity)) {
             case ALLOW:
                 onProceed.run();
                 return;
@@ -51,7 +43,7 @@ public static void guardHeavyStart(@NonNull Activity activity, @NonNull Runnable
                         .setTitle(R.string.k2go_netpolicy_metered_title)
                         .setMessage(R.string.k2go_netpolicy_metered_msg)
                         .setPositive(R.string.k2go_netpolicy_continue, () -> {
-                            consent.grant();
+                            SessionMeteredConsentStore.get().grant();
                             onProceed.run();
                         })
                         .setNegative(R.string.k2go_netpolicy_not_now, null)

controller/app/src/main/java/org/appdevforall/k2go/redesign/SetupLibraryActivity.java

@@ -304,8 +304,15 @@ public void openZimConfirm() {
     public void startZimDownload() {
         ZimWishlist.add(this, selection().zimCart());
         selection().zimCart().clear();   // handed over; keeping it would re-offer the same picks
-        ZimProvisioner.drain(this);      // starts now if the line is free, banks it if not
-        startActivity(new Intent(this, SetupProgressActivity.class));
+        // K2GO-395 (ADR-395 sec.10): the order is banked above, unconditionally, so it is never lost.
+        // The gate wraps only the drain + navigation: it prompts on a metered network and, on consent
+        // (or Wi-Fi), drains and opens progress; declined or offline the order stays queued and a later
+        // pass drains it. The drain is also held headless by ContentAdmission, so a banked order never
+        // starts on metered data without consent even via the wizard-bank path or a background re-drain.
+        org.appdevforall.k2go.networkpolicy.presentation.NetworkPolicyGate.guardHeavyStart(this, () -> {
+            ZimProvisioner.drain(this);      // starts now if the line is free, banks it if not
+            startActivity(new Intent(this, SetupProgressActivity.class));
+        });
     }
 
     /** ADFA-4853: the wizard's "Continue" — install the system now; content (Books/ZIM) is banked

controller/app/src/main/java/org/appdevforall/k2go/redesign/ZimConfirmFragment.java

@@ -106,14 +106,10 @@ public View onCreateView(@NonNull LayoutInflater inflater, @Nullable ViewGroup c
             if (!(getActivity() instanceof SetupLibraryActivity)) return;
             SetupLibraryActivity a = (SetupLibraryActivity) getActivity();
             if (banks) a.zimWizardConfirm();   // no box yet: bank it
-            // ADFA-5074 / ADFA-5333: blocked while a dashboard update runs.
-            // K2GO-395 (ADR-395): gate a metered start behind explicit consent (cost awareness).
-            // The gate sits at the user commit point, not on ZimProvisioner.drain (that re-hands an
-            // already-authorized wishlist every ~2 s and would re-prompt).
-            else if (!DashboardRebuild.blockedByUpdate(v)) {
-                org.appdevforall.k2go.networkpolicy.presentation.NetworkPolicyGate
-                        .guardHeavyStart(a, a::startZimDownload);
-            }
+            // ADFA-5074 / ADFA-5333: blocked while a dashboard update runs. The K2GO-395 metered-cost
+            // gate lives inside startZimDownload (bank first, then gate the drain), so the order is
+            // never lost on decline/offline; see ADR-395 sec.10.
+            else if (!DashboardRebuild.blockedByUpdate(v)) a.startZimDownload();
         });
 
         return root;

controller/app/src/main/java/org/appdevforall/k2go/system/data/ContentAdmission.java

@@ -15,6 +15,7 @@
 import android.util.Log;
 
 import org.appdevforall.k2go.install.presentation.ModuleQueueRepository;
+import org.appdevforall.k2go.networkpolicy.data.NetworkCostAdmission;
 import org.appdevforall.k2go.redesign.DashboardRebuildService;
 import org.appdevforall.k2go.redesign.MapsProvisioner;
 import org.appdevforall.k2go.system.domain.ContentType;
@@ -73,6 +74,15 @@ public static boolean canStart(Context ctx, ContentType stream) {
             Log.d(TAG, stream.key() + " drain deferred: a content stream still has work to do");
             return false;
         }
+        // ADR-395: cost gate. A heavy content download must not start on a metered network without
+        // the user's consent. This is the single headless hold that covers every drain path -- the
+        // commit point, the wizard-bank path, and every background re-drain -- so a banked order
+        // waits for Wi-Fi or consent rather than silently spending mobile data. Prompting happens at
+        // the UI commit point (NetworkPolicyGate); here we only defer.
+        if (!NetworkCostAdmission.allowsHeavyStartNow(ctx)) {
+            Log.d(TAG, stream.key() + " drain deferred: metered network without consent");
+            return false;
+        }
         return true;
     }
 }

controller/docs/ADR-395-network-cost-consent.md

@@ -163,15 +163,22 @@ Landed as a compiling, tested starting point for the implementer:
 - Domain, pure JVM, unit-tested: `NetworkClass`, `NetworkPolicy`,
   `NetworkTransition`, `NetworkPolicyDecision`, `MeteredConsentStore`
   (`NetworkPolicyTest`, `NetworkClassTest`, `NetworkTransitionTest` -- green).
-- Data: `AndroidNetworkClassifier`, `SessionMeteredConsentStore`.
-- Presentation: `NetworkPolicyGate` (+ `BrandDialog` consent), `MeteredNetworkObserver`.
-- Wiring: observer started in `IIABApplication`; gate wired at the ZIM commit
-  point (`ZimConfirmFragment`).
+- Data: `AndroidNetworkClassifier`, `SessionMeteredConsentStore`,
+  `NetworkCostAdmission` (the one classify + consent + policy decision source).
+- Presentation: `NetworkPolicyGate` (the UI prompt, + `BrandDialog`),
+  `MeteredNetworkObserver`.
+- Enforcement (headless): `ContentAdmission.canStart` defers when
+  `NetworkCostAdmission.allowsHeavyStartNow` is false, so the ZIM, Books and
+  Kolibri drains all HOLD a banked order on metered-without-consent (sec.10).
+- Wiring: observer started in `IIABApplication`; the ZIM commit point
+  (`SetupLibraryActivity.startZimDownload`) banks first, then gates the drain, so
+  a declined/offline order is queued, not lost.
 - Strings translated to all 33 locales (machine-generated, pending human review)
   in `values*/strings_networkpolicy.xml`; `strings_untranslated.xml` is clear.
 
-Remaining to finish the contract: the other four seams and the two-way fold of the
-existing `hasInternet` readers into the classifier. (l10n is done pending review.)
+Remaining to finish the contract: the Books/Kolibri commit-point prompts (their
+drains are already held), the Maps seam (re-locate post K2GO-394), the
+DownloadManager seam, and the two-`hasInternet` fold. (l10n done pending review.)
 
 ## 6. Device evidence appendix (dark surfaces flattened)
 
@@ -277,7 +284,26 @@ is complete:
    does not hold the transfer. This is the real depth of the feature and should
    be designed before wiring the remaining seams, not after.
 
-Decision needed (consult, do not default): keep the commit-point gate as a first
-layer and add drain-level consent enforcement, or move enforcement entirely into
-the provisioner/session start. The reference ZIM seam is left as-is pending this
-decision so the trade-off is visible, not silently patched.
+### Resolution (implemented)
+
+Enforcement moved to the single choke every content drain already consults:
+`ContentAdmission.canStart` (system/data) -- "the one answer to may a REST content
+stream start now". It now also defers when `NetworkCostAdmission.allowsHeavyStartNow`
+is false (metered without consent), so ZIM, Books and Kolibri drains all HOLD a
+banked order rather than spend mobile data -- the commit point, the wizard-bank
+path and every background re-drain, covered in one place, with no per-provisioner
+edit and no new persistent state (a held order is simply left banked, the existing
+"deferred is not a failure" contract).
+
+`NetworkCostAdmission` (networkpolicy/data) is the single source of the classify +
+consent + policy decision, used both by that headless admission and by the UI gate.
+
+The prompt stays at the UI commit point (`NetworkPolicyGate`), but banking now
+happens BEFORE the gate (`SetupLibraryActivity.startZimDownload` banks, then gates
+the drain), so a declined or offline order is queued, not lost. This removes the
+commit-point special case rather than adding one.
+
+Still open as follow-ups: the Books/Kolibri commit-point prompts (their drains are
+already held by the ContentAdmission change; only the interactive ask is missing),
+the Maps seam (K2GO-394 reworked Maps; re-locate it), DownloadManager (OTA/portal),
+and the two-`hasInternet` fold.