docs(ahbg): close post-merge Play release truth gaps (#28)

* docs(ahbg): restore complete Play release blockers

* docs(ahbg): correct RevenueCat project and entitlement boundaries

* docs(ahbg): expose runtime and entitlement blockers

Author: erinepshovel-code

ahbg/submission/GOOGLE_PLAY_RUNBOOK.md

@@ -10,10 +10,17 @@ default), and a signed AAB.
 - RevenueCat `purchases:10.19.1` only (no Galaxy module); ordinary
   `PurchasesConfiguration` is the correct Play configuration.
 - Package `org.interdependency.ahbg`; entitlement `benchmark_lab` unchanged.
-- Entitlement lookup is wired, but **purchase initiation and explicit restore
-  controls are not yet implemented**. Do not call the Play billing gate complete
-  until the app can fetch the offering, launch the purchase, and call
-  `restorePurchases` through a user-visible path.
+- Entitlement lookup exists, but the Android/WebView surface currently reads a
+  synchronous Boolean while RevenueCat refreshes customer info asynchronously.
+- Purchase initiation and explicit restore controls are not yet implemented.
+- Verified client-to-runtime entitlement transport and enforcement of the
+  premium operations are not yet implemented.
+- `BuildConfig.RUNTIME_URL` points at the intended production host, but a source
+  constant is not deployment evidence. Production TLS/reachability and the
+  AHBG runtime service still require end-to-end acceptance.
+
+Do not call the Play billing or publication gate complete until those repository
+boundaries and the live-account boundaries below have been verified.
 
 ## 1. Play Console
 
@@ -23,13 +30,17 @@ default), and a signed AAB.
      testers for at least 14 days before production access.
 2. Create the app (`org.interdependency.ahbg`) and complete the store listing
    with `STORE_LISTING.md`, `PRIVACY_POLICY.md`, icon, and screenshots.
-3. Complete the mandatory **App content** declarations before production:
+3. Complete the mandatory **App content** declarations before production,
+   including the applicable "none" declaration when the app has no such
+   features:
    - Data safety;
    - public privacy-policy URL;
    - ads declaration;
    - app-access declaration/instructions;
-   - target audience and content declarations; and
-   - content-rating questionnaire.
+   - target audience and content declarations;
+   - content-rating questionnaire;
+   - Financial features declaration; and
+   - Health apps declaration.
 
 ## 2. Release artifact (Play-native AAB)
 
@@ -71,14 +82,34 @@ provisioned). Upload the signed AAB as the first internal/closed test release.
    activate.
 6. In RevenueCat, map product `ahbg_benchmark_lab` → entitlement
    `benchmark_lab` → default offering.
-7. Copy the Google Play app's RevenueCat **public SDK API key** (`goog_...`)
-   into the Android build. `rc_...` identifies RevenueCat project resources;
-   it is not the Google Play Android SDK key.
+7. Record the RevenueCat project ID exactly as shown by RevenueCat; v2 project
+   IDs use the `proj...` form. This is project metadata, not an Android SDK key.
+8. Copy the Google Play app's RevenueCat **public SDK API key** (`goog_...`)
+   into the Android build.
 
-## 5. Sandbox purchase + restore + persistence verification
+## 5. Repository billing and entitlement gate
 
-This gate is **repository-blocked until purchase and restore controls are
-wired**. Once that code exists:
+Sandbox verification is **repository-blocked** until all of these are real:
+
+1. fetch the current RevenueCat offering/package and initiate purchase of
+   `ahbg_benchmark_lab` from a user-visible control;
+2. expose an explicit restore control using RevenueCat restore and handle
+   success/cancel/error outcomes;
+3. notify/refresh the WebView when asynchronous customer-info refresh changes
+   `benchmark_lab`, including on cold start rather than relying on one early
+   synchronous read;
+4. carry a server-verifiable entitlement claim to the runtime and enforce it at
+   the premium operations instead of changing only a local status label; and
+5. deploy the production runtime and verify TLS, `board.html`, session creation,
+   plan/state calls, entitlement checks, and the premium gate through the exact
+   production URL.
+
+Do not replace these with a local Boolean, a documentation assertion, or an
+unverified client field.
+
+## 6. Sandbox purchase + restore + persistence verification
+
+Once section 5 exists:
 
 1. Play Console → Settings → License testing: add the Google account that will
    perform the billing test. Test-track membership alone does not make a
@@ -87,19 +118,24 @@ wired**. Once that code exists:
    install the Play-delivered test release.
 3. Verify free tier: basic play and external harness connectivity work.
 4. Fetch the current RevenueCat offering and initiate purchase of
-   `ahbg_benchmark_lab`; confirm `benchmark_lab` unlocks.
+   `ahbg_benchmark_lab`; confirm the verified runtime premium surface unlocks.
 5. Invoke the app's explicit restore path; confirm the entitlement re-activates
-   for the same store account.
-6. Force-stop and relaunch; confirm the entitlement remains correct.
-
-## 6. Production
-
-1. Complete the required closed test if the account is subject to it.
-2. Complete all App content declarations and resolve every Play Console
+   for the same store account and the WebView receives the refreshed state.
+6. Force-stop and relaunch; confirm asynchronous customer-info refresh restores
+   the correct state without requiring a page reload or second app start.
+7. Exercise one premium operation and prove the runtime rejects it without a
+   valid entitlement and accepts it with the verified entitlement.
+
+## 7. Production
+
+1. Deploy the production AHBG runtime at the exact configured HTTPS URL and run
+   the end-to-end health checks in section 5 from a release-equivalent client.
+2. Complete the required closed test if the account is subject to it.
+3. Complete all App content declarations and resolve every Play Console
    publication blocker.
-3. Apply for production access, promote the release, obtain the public Play
+4. Apply for production access, promote the release, obtain the public Play
    Store URL.
-4. Use that URL as the Devpost entry.
+5. Use that URL as the Devpost entry.
 
 ## Galaxy (deferred/optional)
 
@@ -109,7 +145,8 @@ and follow the archived Galaxy notes.
 
 ## hmmm
 
-The repository can prepare the AAB and entitlement boundary, but Play account
-approval, live service credentials, store policy declarations, and the real
-billing transaction remain external. Purchase/restore UI is still repository
-work and must be completed before sandbox verification.
+The repository can build the AAB and observe an existing RevenueCat entitlement,
+but acquisition, asynchronous UI refresh, verified runtime enforcement, and
+production-runtime acceptance remain repository work. Play account approval,
+live service credentials, policy declarations, and the real billing transaction
+remain external.

ahbg/submission/REVENUECAT_PROVISIONING.md

@@ -2,13 +2,15 @@
 
 The entitlement-check integration exists (`Entitlements.kt` + runtime
 `entitlements.py`). Live provisioning needs the RevenueCat dashboard, Play
-Console, and Google Cloud. Purchase initiation and explicit restore controls
+Console, and Google Cloud. Purchase initiation, explicit restore controls,
+asynchronous WebView refresh, and verified runtime entitlement enforcement
 remain repository work and are called out separately below.
 
 ## Dashboard + Play connection
 
 1. Create the production project in RevenueCat.
-   - Record the **project id** here once created: `rc_<TO_FILL>`.
+   - Record the **project id** exactly as RevenueCat shows it; v2 project IDs
+     use the `proj...` form.
    - This project id is not an Android SDK API key.
 2. Add a **Google Play** app (`org.interdependency.ahbg`).
 3. Google Cloud Console:
@@ -41,41 +43,73 @@ remain repository work and are called out separately below.
 10. RevenueCat `10.19.1` core supports Google Play through the ordinary
     `PurchasesConfiguration`; no Galaxy store module is required.
 
-## Repository billing controls — not complete
+## Repository acquisition controls — not complete
 
 Before the live Play billing gate can run, AHBG must expose user-visible
 operations that:
 
 1. fetch the current RevenueCat offering/package for `ahbg_benchmark_lab`;
 2. initiate the purchase and handle success/cancel/error outcomes; and
-3. invoke `Purchases.sharedInstance.restorePurchases`, then refresh the
-   entitlement state.
+3. invoke RevenueCat restore, then refresh the entitlement state.
 
 `getCustomerInfo` / `isBenchmarkLabUnlocked()` alone can observe an existing
 entitlement but cannot acquire or explicitly restore one.
 
+## Repository entitlement delivery — not complete
+
+The current store initializes `benchmarkLabUnlocked` to false and refreshes it
+asynchronously. The WebView bridge exposes only a synchronous Boolean read.
+Therefore a cold start can read `false` before RevenueCat answers and never
+learn that the entitlement became active.
+
+Before persistence is called complete:
+
+1. publish an explicit entitlement-state update from the RevenueCat callback to
+   the WebView (or provide an equivalent deterministic refresh path);
+2. update the premium UI when that state changes without requiring a restart;
+3. carry a server-verifiable entitlement claim across the Android/runtime
+   boundary; and
+4. enforce `benchmark_lab` at the actual premium runtime operations, not only
+   at a local label or client-side control.
+
+The client must not be the authority for its own premium claim.
+
+## Production runtime — not complete
+
+`BuildConfig.RUNTIME_URL` names the intended HTTPS host, but the repository does
+not thereby prove that the AHBG service is deployed, reachable, or serving the
+same runtime contract. Before Play publication, verify the production URL from
+a release-equivalent client: board load, session creation, plan/state calls,
+entitlement verification, and one denied/allowed premium operation.
+
 ## Verify (gate items)
 
 Before any billing transaction, configure the purchasing Google account under
 Play Console **License testing** and use that same account to accept/install the
 test-track build. Test-track membership alone is not a sandbox guarantee.
 
-After the repository billing controls above exist:
+After the repository acquisition, entitlement-delivery, and production-runtime
+boundaries above exist:
 
 - **Free tier**: no purchase → inactive entitlement; Benchmark Lab locked;
   basic play and harness connectivity work.
-- **Purchase**: the license-test transaction activates `benchmark_lab` and the
-  premium surface unlocks.
+- **Purchase**: the license-test transaction activates `benchmark_lab`, the
+  asynchronous update reaches the WebView, and the verified runtime premium
+  surface unlocks.
 - **Restore**: the explicit restore control calls RevenueCat restore and
   re-activates the entitlement for the same store account.
-- **Persistence**: entitlement state is re-fetched on launch; after restart the
-  unlocked state remains correct.
+- **Persistence**: entitlement state is re-fetched on launch and the eventual
+  asynchronous result updates the page; an early synchronous false cannot
+  remain stuck for the session.
+- **Enforcement**: a premium runtime operation rejects an unverified/inactive
+  claim and accepts a valid active entitlement.
 - **Degraded/offline**: RevenueCat errors/no-network default to the free tier;
   basic AHBG remains usable.
 
 ## hmmm
 
 - Actual project id, product configuration, service-account JSON, and `goog_...`
   SDK key require live accounts and cannot be provisioned from this repository.
-- The Play sandbox billing verification remains blocked until purchase/restore
-  controls are implemented in the Android surface.
+- The Play sandbox billing verification remains blocked until purchase/restore,
+  asynchronous entitlement delivery, runtime enforcement, and production
+  deployment acceptance are implemented.

ahbg/submission/SUBMISSION_BLOCKERS.md

@@ -1,8 +1,9 @@
 # AHBG submission blockers — Google Play (primary)
 
-The Android release artifact and entitlement-check boundary are source-ready.
-The remaining blockers are split below between repository work and live external
-Play/RevenueCat work so a green build is not mistaken for a publishable app.
+The Android release artifact is source-buildable, but the billing/acquisition,
+entitlement-delivery, runtime-enforcement, and production-deployment boundaries
+are not complete. The remaining blockers are split below so a green build is
+not mistaken for a publishable or sellable app.
 
 ## 1. Construction (core mechanics) — CLOSED
 
@@ -13,29 +14,50 @@ Play/RevenueCat work so a green build is not mistaken for a publishable app.
 - Post-merge hardening is owned by UCNS; AHBG does not invent replacement
   construction geometry.
 
-## 2. Billing controls — REPOSITORY BLOCKER
+## 2. Billing + entitlement enforcement — REPOSITORY BLOCKERS
 
-RevenueCat initialization and entitlement lookup exist, but the Android/WebView
-surface does not yet expose a complete acquisition flow.
+RevenueCat initialization and an asynchronous customer-info lookup exist, but
+the Android/WebView/runtime path does not yet form a complete premium gate.
 
 - **Blocker**: fetch the current RevenueCat offering/package.
 - **Blocker**: launch purchase of `ahbg_benchmark_lab` from a user-visible
   control and surface success/cancel/error state.
-- **Blocker**: expose an explicit restore control that calls
-  `Purchases.sharedInstance.restorePurchases` and refreshes entitlement state.
-- Regression-test the bridge/API boundary; do not mark the sandbox billing gate
-  complete from `getCustomerInfo` alone.
-
-## 3. Google Play publication — EXTERNAL (primary path)
-
-- Code compliance is done: `compileSdk`/`targetSdk` 36, AGP 8.9.1, Gradle
-  8.11.1, Play-native `bundleRelease` in CI, RevenueCat 10.19.1 core, production
-  HTTPS endpoint, signing config outside Git.
+- **Blocker**: expose an explicit restore control using RevenueCat restore.
+- **Blocker**: notify/refresh the WebView when asynchronous customer-info refresh
+  changes `benchmark_lab`; one synchronous read during page startup is not
+  persistence evidence.
+- **Blocker**: carry a server-verifiable entitlement claim to the runtime rather
+  than trusting a local client Boolean.
+- **Blocker**: enforce `benchmark_lab` at the actual premium runtime operations;
+  a changed status label is not feature gating.
+- Regression-test the acquisition, async-refresh, transport, and deny/allow
+  runtime boundaries before calling the billing gate complete.
+
+## 3. Production AHBG runtime — REPOSITORY/DEPLOYMENT BLOCKER
+
+The Android build carries an intended production `RUNTIME_URL`; that build-time
+constant is not proof that the service exists or is healthy.
+
+- **Blocker**: deploy the canonical AHBG runtime at the exact configured HTTPS
+  URL with valid TLS.
+- **Blocker**: verify from a release-equivalent client that `board.html`, session
+  creation, plan/state calls, entitlement verification, and a premium deny/allow
+  operation work end to end.
+- Preserve the Android layer as transport/presentation only; do not repair a
+  missing service by embedding a second runtime into the app.
+
+## 4. Google Play publication — EXTERNAL (primary path)
+
+- Code/build compliance is present: `compileSdk`/`targetSdk` 36, AGP 8.9.1,
+  Gradle 8.11.1, Play-native `bundleRelease` in CI, RevenueCat 10.19.1 core,
+  and signing config outside Git.
 - **Blocker**: Play developer account, app registration, first internal/closed
   test release upload, and production promotion.
 - **Blocker**: complete Play Console App content requirements: Data safety,
   public privacy-policy URL, ads declaration, app-access declaration, target
-  audience/content declarations, and content-rating questionnaire.
+  audience/content declarations, content-rating questionnaire, Financial
+  features declaration, and Health apps declaration. Where AHBG has no
+  financial/health features, submit the corresponding "none" declaration.
 - **Blocker**: create and activate the `ahbg_benchmark_lab` non-consumable
   one-time-product purchase option, including price and regional availability.
 - **Blocker**: configure the billing-test Google account under Play Console
@@ -45,20 +67,19 @@ surface does not yet expose a complete acquisition flow.
   Google currently requires 12 continuously opted-in testers for at least 14
   days before production access — start the closed test immediately.
 
-## 4. RevenueCat production provisioning — EXTERNAL
+## 5. RevenueCat production provisioning — EXTERNAL
 
-- Client/runtime entitlement-check boundary complete.
 - **Blocker**: live RevenueCat project, Google Play app, Google Cloud service
   account (Play Developer + Reporting APIs), Play permission grants,
   service-account JSON upload, product/entitlement/offering mapping, and the
   Google Play app's RevenueCat public SDK key (`goog_...`).
-- `rc_...` project identifiers are not valid substitutes for the Android Google
-  Play public SDK key.
+- RevenueCat v2 project IDs use the `proj...` form; project IDs are not valid
+  substitutes for the Android Google Play public SDK key.
 - **hmmm**: RevenueCat/Google Play service-account permissions can take time to
   propagate after provisioning.
   See `REVENUECAT_PROVISIONING.md`.
 
-## 5. Publish + submission assets — EXTERNAL
+## 6. Publish + submission assets — EXTERNAL
 
 - Store listing, privacy policy, demo storyboard, Play runbook, and Devpost
   material are in `ahbg/submission/`.
@@ -78,13 +99,22 @@ and follow the archived Galaxy notes.
   change; signing needs the production keystore outside Git.
 - Connect conforming harness / A0 same contract / build / persist / reload:
   verified by `ahbg/runtime` tests and the HTTP bridge.
-- Sandbox purchase → `benchmark_lab` unlock → restore → restart persistence:
-  **BLOCKED** until purchase/restore controls are implemented, then requires
-  the Play test track, License testing account, active purchase option, and
-  RevenueCat Play credentials.
+- Sandbox purchase → async entitlement refresh → verified runtime unlock →
+  restore → restart persistence → premium deny/allow: **BLOCKED** until the
+  repository work in sections 2–3 is implemented, then requires the Play test
+  track, License testing account, active purchase option, and RevenueCat Play
+  credentials.
+
+## Smallest repository next action
+
+Add one explicit entitlement-state notification/refresh path from
+`RevenueCatPremiumStore` to the WebView and a regression test proving a cold
+start can transition from the initial locked state to the eventual RevenueCat
+state without restart. This closes one concrete race without pretending that
+purchase, restore, server verification, feature gating, or deployment are done.
 
 ## hmmm
 
-A buildable AAB is not yet a sellable product. The smallest repository-owned
-next step is purchase + restore wiring; the rest of the gate then crosses into
-live Play/RevenueCat accounts.
+A buildable AAB is not yet a sellable product. After the async entitlement
+refresh is repaired, acquisition, verified runtime gating, and production
+runtime acceptance remain living continuation before the external store gate.