# Vanta — working notes

Android 17 ROM on **LineageOS `lineage-24.0`** (real `android-17.0.0_r1`), with our own
UI/feature layer over every surface the user sees. **Targets: Galaxy Z Flip5 (`b5q`, the
default) and a GSI (`gsi_arm64`).** The Galaxy S10+ (`beyond2lte`) was cancelled 2026-10-11 and
stays buildable for reference. BUILD.md is the build host's whole job, PLAN.md the stages and
gates, FEATURES.md the feature tracks, ril/README.md the (S10) mobile-data evidence.
`tools/check.sh` is the gate for anything done on Zo.

**The canonical source is VantaGit**: https://vanta.failure.fail/git/vanta/vanta. The build box
clones it and runs `VANTA_DEVICE=b5q tools/host-run.sh`; Zo's working copy is `Projects/vanta`
(push to `http://127.0.0.1:24900/vanta/vanta.git`, token in
`Projects/vanta-site/data/vantagit-admin.txt`). `Projects/s10-rom` is the older pre-kit copy.

**Base switched 2026-09-24 from Project Infinity X "17" to LineageOS 24.0.**
Infinity's frameworks/base, Settings and Launcher3 were really Android 16
wearing a 17 tag, and the first box build died in Soong analysis on exactly
that (duplicate modules, unknown properties). Lineage 24.0 is the genuine
17 tree and Infinity itself sits on it, so every Vanta surface was re-ported
(all 12 SystemUI patches now apply to lineage-24.0; `build/l24/` holds the
reference clones they are checked against).

## The spine

- **One device profile per target** (`devices/<device>.env`): product, local manifest, make
  target (`bacon` or `systemimage`), whether the S10-only uprev/KernelSU steps run, foldable.
  `tools/lib/profile.sh` loads it for sync/apply/build; none of those scripts names a device.
  `check.sh` fails if one does.
- **Flip5 = official Lineage for everything shared with the S23.** LineageOS maintains
  sm8550-common, the sm8550 kernel (with `b5q_defconfig` and the b5q dts), devicetrees, modules,
  hardware/samsung and TheMuppets' common blobs on `lineage-24.0` (dm1q is official). Only the b5q
  device tree and b5q blobs come from Exynoobs `lineage-23.2`, pinned by full SHA. Lineage's own
  dm1q needed no device change for 24.0, so b5q has no uprev step.
- **The cover is not an app.** When the Flip5 closes, `display_layout_configuration.xml` makes
  the outer panel display 0, so the default HOME lands there. VantaHome is that HOME and
  recomposes as `cover/CoverHome.kt` whenever its window is under 480dp both ways
  (`isCoverSized`). A second HOME app would mean a chooser — the old VantaCover (priority 10
  HOME) was deleted for exactly that; `check.sh` asserts one HOME.

- **vendor/lineage is never patched.** Everything reaches the build through
  `vendor/extra/product.mk`, which Lineage's `common.mk` inherits first. Where
  Lineage installs something the user sees, Vanta goes through Lineage's own
  hook (`lineage_bootanimation.prebuilt_file`), overrides the module where
  ours installs under a different path (`LineageSetupWizard`, `Updater`), or
  rewrites the source Lineage's own module installs where the path is the
  point (`fonts_customization.xml` via `tools/fonts.sh`, recovery art via
  `tools/recovery.sh`) — never a second module at the same path. `verify_tree.py` checks each hook and module
  still exists before a build is spent on it.
- **Branding is generated from the tree it covers.** `gen_branding.py`
  (LineageOS→Vanta strings, every locale the target translates into),
  `gen_fonts.py` (Lineage's fonts_customization.xml + IBM Plex),
  `gen_recovery.py` (recovery header/animation at the tree's own sizes) all
  have `--check`, run by `apply.sh` against the synced tree. Recovery art goes
  in by file name via `tools/recovery.sh`; its palette/title is
  `patches/bootable/recovery/`.
- **The device trees are 23.2 upstream plus `device/uprev.py`.** No fork, no
  hand edits on the box. Every change is an anchored, idempotent edit that
  fails loudly when its anchor moves. Fixing an Android 17 build break means
  adding an edit there and a fixture case in `check.sh`.
- **`design/tokens.json` is the single source** for overlays and the
  identity. `tools/gen_overlays.py` writes the resource files; `--check`
  fails on drift. Don't hand-edit anything it generates.

## Traps

- **Silent misses are the main risk.** An overlay that names a resource the
  target lacks does nothing and reports nothing. A `-include` of a moved path
  is skipped. A boot animation copied second loses without a warning.
  `verify_tree.py` checks each of these against the real tree.
  `def_animator_duration_scale` was in the first draft and does not exist
  in AOSP 17.
- **Mobile data is why the phone ran Infinity 3.12.** A full diff of the
  Infinity 3.12 and LineageOS 23.2 images (vendor, system props, kernel config,
  RROs) found one telephony difference: `config_num_physical_slots = 2`.
  The RIL blobs are byte-identical and LineageOS builds
  `cbd`/`secril_config_svc`/`sehradiomanager` from source, so don't go looking
  for missing blobs again.
- **Theme JSON is merged, never written wholesale**, and the font is a key
  in it (the theme engine disables unnamed overlays at boot). Both were learned
  on this phone; `TestIdentity` guards the merge. Lineage ships no IBM Plex, so
  `FontIBMPlexSansOverlay` + the two variable TTFs are ours.
- **An RRO string in values/ loses to the target's values-en-rGB/.** That is
  why the brand overlays are generated per locale from the tree's own
  translations rather than written once in English.
- **Lineage's boot animation installs to /product/media**, which is read
  before /system/media: a PRODUCT_COPY_FILES to system silently loses.
- **Recovery's font is an ASCII bitmap.** No `·` or other non-ASCII in
  anything recovery prints; `check.sh` greps the patch for it.
- **17 moved pixel's power and thermal HALs into their own soong namespaces**
  (`hardware/google/pixel/power-libperfmgr`, `.../thermal`), so the 23.2 common
  tree's export of `hardware/google/pixel` no longer reaches them and Kati calls
  the services non-existent. 17 also deleted `hardware/interfaces/configstore`,
  so `disable_configstore` has nothing to build. `device/uprev.py` fixes both;
  the first lineage-24.0 run died on exactly these four modules (2026-09-24).
- **On 17, two modules can never install the same path, and `overrides:`
  does not change that.** Soong writes a Kati install rule for *every* module
  (`build/soong/android/makevars.go`, `writeInstalls`), selected or not, so
  `vanta_fonts_customization.xml` with `overrides: ["fonts_customization.xml"]`
  killed the second lineage-24.0 run in Kati ("overriding commands for target
  …/product/etc/fonts_customization.xml", 2026-09-24). `verify_tree.py` now
  fails on any Vanta prebuilt that shares an install path with a Lineage one.
- **Property values with spaces can't go in `PRODUCT_*_PROPERTIES`.** They
  live in `vendor/vanta/props/system.prop` via `TARGET_SYSTEM_PROP`.
- **Soong parses every `android_app_import`**, so no import may point at an
  absent APK. The optional ones (S10Bridge, ZodroidHalo) are declared only in
  `prebuilt/Android.bp`, which `tools/stage.sh` writes for what it staged.
- **A `prebuilt_etc` installs under its module name.** `privapp-permissions-x`
  without `.xml` is ignored by PackageManager — on an enforcing build that is a
  bootloop. Name the module `...xml` (check.sh asserts it).
- **PRODUCT_COPY_FILES is first-wins, and AOSP's AllAudio.mk comes first** (device
  products inherit full_base_telephony before Lineage's common.mk reaches us), so
  every tone has a `Vanta_` name and the defaults are re-pointed by overlay.
- **Shadow-compile at AOSP 17's versions, with no global opt-in.** `tools/shadow`
  pins Kotlin 2.2.0, Compose 1.12.0-alpha01, Material3 1.5.0-alpha16 (what
  prebuilts/sdk vendors at android-17.0.0_r1). At Compose 1.7 the drawer's
  `animateItemPlacement` compiled; on 17 it does not exist.
- **Kotlin nests block comments**: `devices/*.env` inside a `/** */` opens a
  second comment and swallows the rest of the file ("Unclosed comment").
- **zsh is the Zo shell**: unquoted `$files` is not word-split and `path` is a
  special array. Run multi-file loops under `bash -c`.
- **Output names**: bacon writes `lineage-24.0-<date>-UNOFFICIAL-Vanta0.1-<device>.zip`;
  `build.sh` hard-links it as `Vanta-<ver>-<date>-<device>.zip`. The GSI is
  `m systemimage`, published as `Vanta-<ver>-<date>-gsi_arm64.img.xz`. Lunch is
  `<VANTA_PRODUCT> cp2a userdebug`.
- **The build box wipes everything outside `/home/workspace` on reboot** —
  `/root`, apt packages, `/usr/local/bin/repo`, the root password. The tree
  lives at `/home/workspace/vanta`, the kit at `/home/workspace/vanta-kit`,
  and `vanta-kit/tools/host-run.sh` re-runs bootstrap → sync → apply →
  build (log: `vanta-run.log`). After a reboot, re-add Zo's key
  (`/home/workspace/.vanta-ssh/authorized_keys`) and re-run that script.
- **EMFILE on the build box is the sandbox, not `ulimit`.** After the 10-hour
  run the box's gVisor sentry was out of *host* file handles: any process got
  "too many open files" after 300–1,000 opens while `ulimit -n` said 1,048,576
  and only ~250 fds were open inside. (Go raises its own soft limit anyway, so
  the `ulimit` line in `host-run.sh` never mattered.) Only restarting the box
  clears it. `tools/fdprobe.py` runs before sync and before build and fails
  with that instruction instead of letting Soong die at the finder.
- **The unattended run is `tools/host-run.sh`** (tmux session `vanta`), which
  checks every step by exit code. The first box run wrapped the steps in
  `{ } || echo FAILED`, which switches `set -e` off: a sync that 429'd on 131
  repos went on to apply and "build". GitHub rate-limits a `-j64` fetch, so
  `sync.sh` starts at `-j16` and backs off.
- **The box holds a full copy of this project** at
  `/home/workspace/vanta-kit` (every watcher push). Zo's own workspace was
  rolled back on 2026-09-24 and this directory vanished with it; it was
  restored from that copy (minus `out/` and `build/`, which the push
  excludes, so the shadow Gradle builds and the l24 reference clones need
  regenerating before they are relied on).
- **Flashing wipes the phone**, and anything on the phone needs Zandy's go
  first.

## Where things come from

Boot animation: Vanta's own, `tools/bootanim/` (forked from failure-s10's,
IBM Plex wordmark) → `out/bootanim/`. Bridge APK:
`Projects/failure-s10/apk/dist` (newest). Halo: `Projects/zodroid/rom/apk`.
Staged into `vendor/vanta/prebuilt/` (gitignored), then pushed with the kit by
`tools/push.sh user@host`.

## Gates that run on Zo

`tools/check.sh` (about 160 checks, ~15 min; `CHECK_SHADOW=0` / `CHECK_NET=0` skip the Gradle
compile and the clones). Beyond the original gates it now proves: every profile loads; the Flip5
manifest pins are full SHAs and carry both blob repos; `verify_tree.py --device b5q|gsi_arm64`
pass on synthetic trees and fail on a missing blob repo, kernel config or cover display layout;
every app is packaged; permission files keep their `.xml`; tones never collide; one HOME app;
cover panels and home cards match their config ids; `tools/patchcheck.sh` applies the whole
patch series to fresh sparse lineage-24.0 clones; `tools/shadow/build.sh` compiles every app.
`tools/preview/build.sh` renders VantaHome and the cover headlessly (Robolectric, native
graphics), then `tools/preview/compose.py` layers them the way the phone does — Vanta Liquid
(the wallpaper, rendered from the ROM's own shader by `tools/preview/wallpaper.py`) behind,
SystemUI's Rail and status line on top — into `docs/preview/home/` (stills + `home-tour.mp4`,
`cover-tour.mp4`). `tools/preview/system_media.py` makes `docs/preview/system/` (boot animation
and recovery installer videos from their real frames); `design/render/render.py --device
flip5-main` the full surface set in `docs/preview/surfaces/`. A look, not a gate. Robolectric
applies no system-bar insets, so the cover is composited without chrome.
