fix(compiler): gate HoloQR release on HoloScript source

PASS: pnpm check:holoqr-born-from-source

Author: brianonbased-dev

apps/quest-universal-qr-scanner/README.md

@@ -1,84 +1,86 @@
-# Universal QR Scanner — Meta Quest 3 / 3S
+# HoloQR - Universal QR Scanner for Meta Quest
 
-The Quest can't natively scan arbitrary QR codes (Meta restricts native scanning to WiFi
-provisioning). This app fills that gap: launch it, point the headset's passthrough cameras at
-any QR code, and it decodes the value and opens URLs in the Quest Browser.
+HoloQR fills a gap in Quest: it scans arbitrary QR codes through the headset passthrough cameras,
+decodes them on-device, opens ordinary links in Quest Browser, and enters HoloScript worlds from
+world links.
 
-First HoloScript-authored app targeting a major XR store. Source of truth is
-[`scanner.holo`](./scanner.holo); the Android project under [`android/`](./android) is the
-materialization. Origin + full build record:
-`ai-ecosystem/research/2026-06-19_universal-qr-scanner-quest-build.md`.
+This is a HoloScript-authored app, not a native app with a HoloScript label. The source of truth is
+[`scanner.holo`](./scanner.holo) plus [`worlds/`](./worlds). The immersive Quest project under
+[`android-mr/`](./android-mr) is compiler output and a bounded native bridge for platform APIs.
+
+## Release invariant
+
+The only supported shipping path is:
+
+```text
+scanner.holo + worlds/*.holo
+  -> HoloCompositionParser + QuestCompiler
+  -> generated android-mr sources
+  -> independent golden-diff verification
+  -> signed Gradle release APK
+```
+
+The release command runs that entire source gate before it resolves signing secrets or invokes
+Gradle. A direct `gradlew assembleRelease` can be useful during native debugging, but it is not a
+shipping command because it does not prove the APK came from the current HoloScript source.
 
 ## How it works
-- **2D panel app** (not an immersive VR scene). Runs in the Quest windowed environment.
-- **Passthrough camera** via standard Android **Camera2** (Meta exposes the headset cameras as
-  logical Camera2 devices). Selects the forward passthrough RGB camera using Meta's vendor
-  `CameraCharacteristics` (`com.meta.extra_metadata.camera_source==0`, `position==0`).
-- **Decode** on the YUV Y (luminance) plane with **ZXing core** (`com.google.zxing:core:3.5.3`) —
-  GMS-free, because Quest/Horizon OS has no Google Play Services (ML Kit unbundled would not work).
-- **Open URL** in the Quest Browser via the documented Web Task scheme:
-  `ovrweb://webtask?uri=<url-encoded-url>` (plain `https` `ACTION_VIEW` is *not* the Quest path).
-- **Privacy**: frames are decoded on-device; nothing is stored or transmitted.
+
+- Camera frames come from Quest's Android Camera2 passthrough path.
+- ZXing decodes the YUV luminance plane locally; Google Play Services are not required.
+- Ordinary URLs open in the full Quest Browser, with the Web Task scheme as a fallback.
+- HoloScript world links enter compiler-generated immersive scenes.
+- Camera frames are not stored or transmitted.
 
 ## Requirements
-- Quest 3 / 3S on **Horizon OS v76+** (Camera2 passthrough code path).
-- The user grants the `Headset cameras` permission on first run (system-enforced opt-in + a
-  persistent recording indicator while scanning — do not attempt to suppress it).
+
+- Meta Quest 3 or 3S on a Horizon OS version that exposes passthrough Camera2 access.
+- JDK 17 and the Android SDK for local native builds.
+- The user-granted `Headset cameras` permission.
 
 ## Build
 
-### Option A — Cloud build (recommended; no local toolchain)
-A GitHub Actions workflow is committed at
-`.github/workflows/quest-qr-scanner-build.yml`. It builds the release APK and uploads it as an
-artifact. To get a **signed** APK, add these repo secrets (base64 your keystore):
+Run these commands from the HoloScript repository root:
 
-| Secret | Value |
-|---|---|
-| `KEYSTORE_BASE64` | `base64 -w0 release.keystore` |
-| `KEY_ALIAS` | your key alias (e.g. `quest_qr`) |
-| `KEYSTORE_PASSWORD` | keystore password |
-| `KEY_PASSWORD` | key password |
+```bash
+pnpm holoqr:generate-native
+pnpm check:holoqr-born-from-source
+pnpm holoqr:build-release
+```
 
-Trigger it from the Actions tab (`workflow_dispatch`) or by pushing a change under
-`apps/quest-universal-qr-scanner/**`. Without the secrets it still builds an **unsigned** release APK.
+- `holoqr:generate-native` materializes the Quest app from HoloScript.
+- `check:holoqr-born-from-source` compiles and independently verifies the native reference without
+  accessing signing custody or running Gradle.
+- `holoqr:build-release` runs the same gate, then resolves signing custody and builds the signed APK.
 
-### Option B — Local build
-Requires JDK 17, Android SDK (Build-Tools 34+, Platform 34). Then:
-```bash
-cd android
-node ../generate.mjs                  # refresh spec-driven resources
-gradle wrapper --gradle-version 8.9   # one-time: create the gradle wrapper jar
-cp keystore.properties.example keystore.properties   # then edit with your keystore (gitignored)
-./gradlew assembleRelease
-# -> app/build/outputs/apk/release/app-release.apk
+The signed artifact is written to:
+
+```text
+apps/quest-universal-qr-scanner/android-mr/app/build/outputs/apk/release/app-release.apk
 ```
 
-### Signing — generate a keystore once
+See [`RELEASE.md`](./RELEASE.md) for HoloKey signing custody, Meta validation, and store submission.
+
+## Install on a Quest
+
+For a sideloaded test build:
+
 ```bash
-keytool -genkeypair -v -keystore release.keystore -alias quest_qr \
-        -keyalg RSA -keysize 2048 -validity 10000
+adb install -r apps/quest-universal-qr-scanner/android-mr/app/build/outputs/apk/release/app-release.apk
 ```
-Keep `release.keystore` safe — it is the app's identity on the store. Never commit it (`.gitignore`
-already excludes `*.keystore`, `*.jks`, and `keystore.properties`).
 
-## Install on a Quest (sideload, for testing)
+Install through an ALPHA or BETA release channel before public submission when validating the exact
+store-signed artifact.
+
+## Change the app
+
+Edit [`scanner.holo`](./scanner.holo) or a world under [`worlds/`](./worlds), then run:
+
 ```bash
-adb install -r app-release.apk
-# launch it from the headset's app library (Unknown Sources)
+pnpm holoqr:generate-native
+pnpm check:holoqr-born-from-source
 ```
 
-## Publish to the Meta Horizon Store
-1. Create a developer **organization** at the Meta Horizon Developer Dashboard and complete
-   **Admin Verification** (government-issued ID — an individual can publish this way; no DUNS, no
-   documented fee).
-2. Host a **Privacy Policy** URL (template: app decodes QR codes on-device using the headset
-   camera; no frames stored or transmitted) — required because the app accesses the camera.
-3. Create an app, upload the **signed APK** (Horizon Store takes APK; AAB is not documented as
-   accepted). Target SDK ≥ 32, min SDK 34.
-4. Push to an **ALPHA / BETA release channel** first (invite-only, low friction) to validate
-   on-device, then promote to **Production** (triggers full app review).
-
-## Changing app config
-Edit [`scanner.holo`](./scanner.holo), then `node generate.mjs`. That rewrites
-`android/app/src/main/res/values/generated.xml` (app name, privacy note, frame size, camera
-selection, dedupe window, webtask scheme), which the Kotlin reads at runtime.
+Never hand-edit compiler-owned files under `android-mr/`. Native bridge files should contain only
+platform capabilities that the HoloScript compiler/runtime cannot yet express, and each such bridge
+is an explicit language gap rather than a second product source of truth.

apps/quest-universal-qr-scanner/RELEASE.md

@@ -6,7 +6,9 @@ your Meta developer identity — neither can (or should) be done by an agent.
 
 > Native principle (F.126): the app icon, `build.gradle.kts`, and `AndroidManifest.xml` are
 > **`@generated` from `scanner.holo`** by the quest compiler. To change app metadata (version, icon
-> colors, name), edit `scanner.holo` and recompile — never hand-edit `android-mr/`.
+> colors, name), edit `scanner.holo` and recompile — never hand-edit `android-mr/`. The canonical
+> signed-build command compiles `scanner.holo` plus `worlds/*.holo`, verifies the materialization
+> independently, and only then accesses signing custody or invokes Gradle.
 
 ---
 
@@ -31,17 +33,17 @@ your Meta developer identity — neither can (or should) be done by an agent.
 
 Review runs **Technical → Content → Publishing**. Mandatory technical VRCs and our status:
 
-| VRC | Requirement | Status |
-|---|---|---|
-| Packaging.2 | APK v2 signature | ✅ verified v2 |
-| Packaging.6 | 64-bit (arm64-v8a) only | ✅ fixed — arm64-only |
-| Packaging.1 | Manifest conforms (VR category, version) | ✅ emitted |
-| Packaging.5 | APK < 1 GB | ✅ ~120 MB |
-| Functional.14 | Passthrough app launches in passthrough | ✅ `enablePassthrough(true)` on scene-ready |
-| Functional.1 / 5 | No crashes; responds to head tracking | ▶ playtest (BETA channel) |
-| Performance.1 / 3 | Hits refresh rate; graphics ≤ 4 s or VR loader | ▶ playtest (lightweight panel + passthrough) |
-| Security.2 | Minimum permissions | ⚠ manifest declares `HAND_TRACKING`/`RENDER_MODEL` (Spatial-SDK starter inheritance) the scanner may not use — trim after a headset test confirms controller input still works; not a hard blocker |
-| Security.1 | Entitlement check | ➖ **recommended, NOT required** — no Platform SDK integration needed |
+| VRC               | Requirement                                    | Status                                                                                                                                                                                             |
+| ----------------- | ---------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Packaging.2       | APK v2 signature                               | ✅ verified v2                                                                                                                                                                                     |
+| Packaging.6       | 64-bit (arm64-v8a) only                        | ✅ fixed — arm64-only                                                                                                                                                                              |
+| Packaging.1       | Manifest conforms (VR category, version)       | ✅ emitted                                                                                                                                                                                         |
+| Packaging.5       | APK < 1 GB                                     | ✅ ~120 MB                                                                                                                                                                                         |
+| Functional.14     | Passthrough app launches in passthrough        | ✅ `enablePassthrough(true)` on scene-ready                                                                                                                                                        |
+| Functional.1 / 5  | No crashes; responds to head tracking          | ▶ playtest (BETA channel)                                                                                                                                                                          |
+| Performance.1 / 3 | Hits refresh rate; graphics ≤ 4 s or VR loader | ▶ playtest (lightweight panel + passthrough)                                                                                                                                                       |
+| Security.2        | Minimum permissions                            | ⚠ manifest declares `HAND_TRACKING`/`RENDER_MODEL` (Spatial-SDK starter inheritance) the scanner may not use — trim after a headset test confirms controller input still works; not a hard blocker |
+| Security.1        | Entitlement check                              | ➖ **recommended, NOT required** — no Platform SDK integration needed                                                                                                                              |
 
 **Founder/submission-side (not build):** Data Use Checkup (declare the passthrough camera — "frames decoded on-device, not stored/transmitted"), Content Guidelines, IARC age rating, and the listing assets. Use a **Release Channel (ALPHA/BETA)** to install on-headset with no review before the public submission.
 
@@ -59,42 +61,55 @@ time — never in a plaintext file. `build-release.mjs` resolves them, materiali
 private tmp file, builds, and **deletes the keystore after the build**.
 
 ### 1a. Generate the keystore (once, ever)
+
 ```bash
 keytool -genkeypair -v \
   -keystore release.keystore \
   -alias quest_qr \
   -keyalg RSA -keysize 2048 -validity 10000 \
   -dname "CN=Joseph Krzywoszyja, OU=HoloScript, O=HoloScript, L=YourCity, S=YourState, C=US"
 ```
+
 **Back up `release.keystore` to two secure locations (offline). Record the passwords.** HoloKey holds
-the *operational* copy; your offline backup is the custody master. Losing the HoloKey KEK ≠ losing the
+the _operational_ copy; your offline backup is the custody master. Losing the HoloKey KEK ≠ losing the
 keystore as long as that offline backup exists.
 
 ### 1b. Store the four secrets in HoloKey (once)
+
 The vault needs a KEK + Postgres in env: `HOLOKEY_PROD_KEK_CURRENT` + `HOLOKEY_PROD_KEK_<ID>`
 (`node scripts/holokey.mjs gen-kek` prints them) and `DATABASE_URL`.
+
 ```bash
 node scripts/holokey.mjs set KEYSTORE_PASSWORD    '<store-password>'
 node scripts/holokey.mjs set KEY_PASSWORD         '<key-password>'
 node scripts/holokey.mjs set KEY_ALIAS            'quest_qr'
 node scripts/holokey.mjs set ANDROID_KEYSTORE_B64 "$(base64 -w0 release.keystore)"
 ```
+
 (I can run these for you secrets-safely — the values go only into the encrypted vault, never into chat
 or a committed/logged file.) Secrets are owner-bound under `HOLOKEY_OWNER` (default `infra`); the build
 must resolve under the same owner.
 
 ### 1c. Build the signed APK
+
 ```bash
 # env: JAVA_HOME (JDK 17) + ANDROID_HOME, plus the HoloKey KEK + DATABASE_URL (so the vault is ON)
-node scripts/build-release.mjs
+pnpm holoqr:build-release
 # → android-mr/app/build/outputs/apk/release/app-release.apk  (signed v2)
 ```
-`build-release.mjs` resolves the four secrets from HoloKey (or, if the vault is OFF — no KEK — from
-matching env vars `KEYSTORE_PASSWORD`/`KEY_PASSWORD`/`KEY_ALIAS`/`ANDROID_KEYSTORE_B64`), writes the
-keystore to a `0o600` tmp file, runs `gradlew assembleRelease`, and unlinks the tmp keystore. **No
-gradle change was needed** — `android-mr/app/build.gradle.kts` already reads `KEYSTORE_FILE`/`…` from
-env. A plaintext `keystore.properties` still works as a *local-only optional override* but is
-gitignored and unnecessary with HoloKey.
+
+`holoqr:build-release` first runs the real HoloCompositionParser and QuestCompiler over
+`scanner.holo` and every bundled world, then runs the independent Quest golden-diff gate. A parser,
+compiler, or generated-output mismatch blocks the build before signing secrets are resolved. For a
+safe proof with no signing or Gradle, run `pnpm check:holoqr-born-from-source`.
+
+After the source gate passes, `build-release.mjs` resolves the four secrets from HoloKey (or, if the
+vault is OFF, from matching env vars
+`KEYSTORE_PASSWORD`/`KEY_PASSWORD`/`KEY_ALIAS`/`ANDROID_KEYSTORE_B64`), writes the keystore to a
+`0o600` temporary file, runs `gradlew assembleRelease`, and unlinks the temporary keystore. The
+`android-mr/app/build.gradle.kts` file already reads `KEYSTORE_FILE` and the other values from env. A
+plaintext `keystore.properties` still works as a local-only optional override but is gitignored and
+unnecessary with HoloKey.
 
 > Verified (2026-06-22): the full resolve → materialize → `assembleRelease` → v2-signed APK → cleanup
 > chain builds GREEN on-device via the env-fallback path (same resolver code the vault uses).
@@ -115,12 +130,13 @@ review-skip path, but a clean utility passes the basic technical/content/privacy
    to install on your headset and verify before public submission.
 5. **Fill listing + declarations** (assets list below).
 6. **IARC age-rating questionnaire** (in-dashboard).
-7. **Data Use questionnaire** — declare the passthrough camera: *"camera frames are processed on-device
-   to decode QR codes; frames are not stored or transmitted."* A **Privacy Policy URL is required**
+7. **Data Use questionnaire** — declare the passthrough camera: _"camera frames are processed on-device
+   to decode QR codes; frames are not stored or transmitted."_ A **Privacy Policy URL is required**
    (see `PRIVACY.md`).
 8. **Submit for review** — Technical → Content → Publishing. Submit ≥ 2 weeks before any target date.
 
 ### Listing assets to provide (24-bit PNG unless noted)
+
 - App icon **512×512** (no transparency) · Spatialized icon **180×180** (transparent)
 - Hero **3000×900** · Cover landscape **2560×1440** · square **1440×1440** · portrait **1008×1440** · mini **1080×360**
 - Logo (transparent) up to **9000×1440** (32-bit)
@@ -133,6 +149,7 @@ I can produce the icon/cover/logo art set from the emitted `ic_launcher.xml` bra
 ---
 
 ## Sources
+
 Meta Horizon publishing docs (upload, manifest, signing, submit, asset guidelines, release channels)
 — verified June 2026. Key facts: APK + v2 signing, `quest3|quest3s` supportedDevices, monotonic
 `versionCode`, App-Lab-merged-into-Store.