# wadamesh — split plan

**Status: executed ✅ — both boards build green from the published fork and the
T-Deck is flash-verified on hardware.** This file is the tracked roadmap for the
split of the LVGL touch-UI firmware out of
[meshcomod](https://github.com/ALLFATHER-BV/meshcomod) into **wadamesh**.

## Done

- `ALLFATHER-BV/MeshCore` — `wada` branch + tag `v1.16.0-wada.0` = the core (MIT;
  `main` tracks upstream). Build-first: carries the full meshcomod core for now.
- `ALLFATHER-BV/wadamesh` — both touch boards build as their own project,
  pulling the core via `lib_deps @ git tag`. No core vendored here.
- **Byte-identical to meshcomod** (delta = build-path strings only): V4 0.05%,
  T-Deck 0.08%. T-Deck flash-verified on hardware — boots + runs from the split.
- Two fixes were all it took for the build-first split: `build_as_lib.py`
  compiles `helpers/input/`; the bundled `ed25519` lib travels with the project.
- **Fork minimized ✅ (tag `v1.16.0-wada.1`).** The 26 touch/app additions (touch
  HW drivers, prefs/SD helpers, companion transport servers, HTTP-OTA helpers,
  LVGL allocator, touch diag) were relocated to wadamesh; only 3 transport-header
  includes needed fixing. The fork's diff vs upstream dropped **52 files / ~4.2k
  insertions → 24 files / ~1.7k** — just the modified-core hooks. Both boards
  still build green + size-identical from the published tag.

## Remaining (non-blocking)

- **Re-home the release pipeline** to wadamesh (tagged bins as GitHub Release
  assets, not 1.2 GB in-tree; on-device OTA + flasher + wadamesh.com).
- Optional polish: dedupe the two envs' shared flags into a common base; prune
  unused `boards/*.json`.

## Goal

Split the touch-UI firmware (LilyGo T-Deck / T-Deck Plus + Heltec V4 TFT) out of
the meshcomod MeshCore fork into its own repo, **wadamesh**, depending on a clean
MeshCore fork via PlatformIO `lib_deps`. The result must be **behavior-identical
to the shipping betas** — this is mechanical repackaging, **not a refactor**.

## Repos & licensing — done

| Repo | Visibility | License | Role |
|---|---|---|---|
| `ALLFATHER-BV/wadamesh` | private (for now) | **GPL-3.0** | the app: `ui-touch` + companion app glue + variants. Copyleft so distributed builds/forks stay open. |
| `ALLFATHER-BV/MeshCore` | public | **MIT** | fork of `meshcore-dev/MeshCore`; the core wadamesh depends on. Stays MIT so the Wi-Fi/BLE hooks are upstreamable. |

Dependency arrow: **GPL app → `lib_deps` @ git tag → MIT core.** MIT is
GPL-compatible; MeshCore-derived files inside wadamesh keep their MIT headers
(see `NOTICE`).

## Decisions locked

- **Fork scope = minimal & upstreamable.** The fork carries only the genuine core
  hooks; everything touch/app-specific moves to wadamesh.
- **Consumption = `lib_deps` @ git tag.** Matches the existing `library.json` +
  `build_as_lib.py` — the MeshCore repo is already a PlatformIO library.
- **No refactor.** Explicitly OUT of scope (regression risk): no `IMeshController`,
  no `MyMesh` slimming, no `ContactInfo` DTOs, no capability `#ifdef`s. The
  existing `MyMesh` ↔ `ui-touch` coupling is preserved exactly as-is.
- **"Both cores" is a maintenance property, not a runtime layer.** `MyMesh`
  extends `BaseChatMesh`, so it recompiles against whichever core `lib_deps`
  resolves (the fork, or `kkazakov/meshcomod`). Not built now; deferred.

## The boundary

Draw the repo line where the code already separates:

- **Core → MeshCore fork:** the genuine mesh/transport hooks in `src/`.
- **App → wadamesh:** `examples/companion_radio/` (MyMesh, main, DataStore,
  AbstractUITask, NodePrefs) + `ui-touch/` + touch helpers +
  `variants/{lilygo_tdeck, heltec_v4_tft}`.

Core→UI is already a clean seam (`AbstractUITask`, 16 virtuals). The UI→core
coupling (~52 `the_mesh.*` calls) is **left as-is** — `MyMesh` moves into wadamesh
*with* the UI, so that coupling stays in-repo and needs no abstraction layer.

## Where each core change goes (the ~4.2k-line `src/` diff vs upstream)

**KEEP in the fork** (minimal hooks, upstreamable):
- `helpers/BaseChatMesh.{cpp,h}` — `sendMessage` / `expected_ack` / `composeMsgPacket` hooks
- `helpers/BaseSerialInterface.h` — transport abstraction surface
- `helpers/esp32/SerialBLEInterface.*` — NimBLE port (ideally behind a build flag)
- small touches: `CommonCLI`, `IdentityStore`, `EnvironmentSensorManager` (evaluate each)

**MOVE to wadamesh:**
- `LvglPsramAlloc.cpp`, `helpers/esp32/{SdNvsPrefs,TouchPrefsStore,WifiRuntimeStore}.*` → app helpers
- `helpers/input/{HeltecV4CapTouch,TDeckTouch,TDeckKeyboard,TDeckTrackball}.*` → `hal/` (prefer pulled libs where they exist)
- `helpers/ui/ST7789LCDDisplay.*` → `hal/`
- `helpers/esp32/{MultiTransportCompanionInterface,TCPCompanionServer,WebSocketCompanionServer}.*` → `app/` (companion transports)
- OTA helpers (`HttpOta*.h`, `RepeaterTcpOtaEmit.h`) → `app/`

**EVALUATE per-file during extraction** (the judgment calls):
- `helpers/ESP32Board.cpp` (+836) — split general board support (stays) vs touch/display init (moves). Biggest call.
- `helpers/ui/{DisplayDriver.h,UIScreen.h}` (+1/+2) — tiny; likely stay in fork.
- `MeshTouchTxTrace.h`, `TouchDiagTrace.*` — dev instrumentation; move or drop.

## Sequence (one topic per commit, behind a build gate)

1. **Fork baseline.** Branch `ALLFATHER-BV/MeshCore`; tag the vanilla baseline.
   Apply the minimal hook set above; tag `v1.16.0-wada.0`.
2. **wadamesh tree.** Add app + `ui-touch` + helpers + `hal/` + `variants/` + a
   root `platformio.ini` with `lib_deps = ALLFATHER-BV/MeshCore@<tag>`.
3. **Build gate.** Both touch envs build green against the fork; firmware matches
   beta_17 behavior on-device.
4. **Release pipeline.** Re-home the release process to wadamesh (new repo/domain,
   same `beta_N` mechanics). Tile-proxy + flasher: shared with meshcomod or
   forked — a separate decision.

Throughout steps 1–4 the **shipping meshcomod checkout is untouched**; the beta
cadence is unaffected.

## Risks / watch-items

- **Minimal extraction is iterative.** If the touch build needs a core symbol, add
  it to the fork as a discrete hook — don't drag in unrelated code.
- **`ESP32Board` split** is the biggest judgment call — review before moving.
- **"Both cores"** validation (building wadamesh on `kkazakov/meshcomod`) is
  deferred until step 3 proves the boundary.
- **Security gate every wadamesh push** — no `CLAUDE.md`, no `.claude/`, no infra
  details.