tai/taicpp/full_transpilation_and_integration.md

# Full whatsmeow transpilation and integration: plan + agent prompt

Date: 2026-10-27. Source snapshot: whatsmeow `v0.0.0-20261027104441-1eec1136a50b`
(local Go module cache). Baseline: detz 1.46.1; gap inventory:
`../research/whatsapp-automation/whatsmeow-surface-audit.md`.

## Goal

Transpile the whatsmeow library to C++ (`detz::wa`) with literally no
exceptions, gaps, or caveats, integrate every feature into the working detz
application, and finish with zero stubs. Scope is defined mechanically, not by
judgment (see the prompt, section 1): every exported symbol in whatsmeow's
non-test, non-generated Go source, plus every generated protobuf message the
library marshals or unmarshals in non-test code, must have a working C++
counterpart proven by the coverage gate.

## Success Criteria

- The coverage script reports 100% of the inventoried API with zero unmapped
  symbols, and the stub detector reports zero hits in `src/whatsapp/`.
- `make`, `make lint`, and `make test` are green on the final tree.
- Every milestone below exited through its uniform gate (spec delta, code,
  oracle differential tests, hostile-input tests plus sanitizer for parsers,
  coverage at 100% for the milestone's API).
- A live linked phone exercised send, receive, read receipts, groups, media
  both directions, and contact sync at least once each (recorded where and
  when in the docs).
- `CHANGELOG.md`, `VERSION`, and an annotated tag exist for the release; no
  output file lives outside `build/`.

## Approach

Small verified slices with independent oracles, not one big rewrite. Each
milestone transpiles one whatsmeow area against Go oracle programs that call
whatsmeow itself (the established `appstate_oracle.go` pattern), so behavior
is proven byte-for-byte rather than self-asserted. Two external methodology
sources shape the gates: a coverage guarantee comes from an inventory plus a
verification script that cross-references every item and re-runs missed ones
(power-mapper), and trusted output comes from deterministic checks the model
cannot argue with, with counterexamples fed back into repair (the VERT
pattern: oracle, differential tests, concrete failing input per defect).
Per-milestone API slices keep every unit small enough to verify strongly.

## Steps (milestones, dependency order)

| Milestone | whatsmeow area | Delivers |
|---|---|---|
| M0 | harness | API inventory script, coverage gate script, stub detector; baseline coverage measured; whatsmeow commit pinned |
| M1 | foundations | token dict freshness check, socket keepalive pings, full iq request/response infra, Noise parity |
| M2 | store | identities with trust tracking, LID map, sessions, contacts (saved/push/business), privacy tokens, message secrets, chat settings |
| M3 | pairing | pair-code linking, passkey, QR hardening, server logout iq |
| M4 | messaging core | all message types both directions, group sender keys, inbox surfacing, read receipts, retry-resend, media-retry |
| M5 | media | upload and download of every type, thumbnails, stickers, newsletter media |
| M6 | groups etc. | all of `group.go`, `newsletter.go`, broadcast/status, business |
| M7 | sync | all app-state collections plus send path plus recovery, history sync download and on-demand, LID migration |
| M8 | user services | presence, privacy settings, blocklist, calls (observe plus reject), user info, QR links, status message |
| M9 | client services | live version fetch, push registration, CST/TC tokens, full event bus (47 types), Messenger/FB transports |
| M10 | integration | CLI/REPL/tools for everything new, docs, zero-stub gate, live smoke suite, changelog, version, tag |

Uniform milestone exit gate: spec delta in `docs/`, warning-free code under
`-std=c++23 -Wall -Wextra -Werror`, oracle differential tests where bytes
cross the boundary, hostile-input tests plus a sanitizer run for every parser,
`make test` green, milestone API at 100% in the coverage script, one commit.

## Validation Plan

- After every milestone: `make`, `make lint`, `make test`, the coverage script
  scoped to the milestone, the stub detector scoped to touched files.
- New or changed parsers: hostile-input section plus the sanitizer script
  before the milestone can exit.
- Byte behavior: Go oracle programs (checked in under `tests/whatsapp_data/`,
  built by script, never hand-written expectations for MACs, hashes, or
  encodings).
- Final: full coverage 100%, stub detector zero, `make test` green, live
  smoke (send, receive, read receipt, group message, image both directions,
  contact sync) against a linked phone, tag created.
- Highest-risk validation: the live phone pass, because it is the only oracle
  for server behavior; it is scheduled in M10 with explicit user-linking steps
  so offline work never blocks on it.

## Risks / Open Questions

- Scale: whatsmeow is about 24k lines plus 107k generated protobuf lines; the
  generated code is data, and only messages the library actually uses need C++
  counterparts, but M4/M7/M9 are still large. Mitigation: the per-milestone
  100% gate makes partial progress shippable and measurable.
- "Verified" is bounded: differential tests prove equivalence on exercised
  paths, not all possible runs. The prompt states this honestly and requires
  hostile fuzzing to widen the net.
- Live verification needs the user's phone at defined points. If the phone is
  unavailable, milestones exit on offline gates and M10 stays open; nothing is
  ever marked live-verified without the run.
- No open design questions: reuse (moloapp), style (cpp-safety), and workflow
  (AGENTS.md) are bound by existing project law cited in the prompt.

## Sources

- https://github.com/richyparr/power-mapper
- https://www.ben-livshits.org/blog/c-to-rust

---

# THE PROMPT (paste verbatim to the transpilation agent)

You are transpiling the whatsmeow Go library to C++ inside
`/home/retoor/projects/tai/taicpp`, module `detz::wa` (`src/whatsapp/`).
Read this whole prompt before touching anything. Your finished state is a
working application with zero stubs and no exceptions, gaps, or caveats.

## 1. Scope (mechanical, not judgment)

The source snapshot is pinned: whatsmeow
`v0.0.0-20261027104441-1eec1136a50b` in the local Go module cache. Record
its commit hash in `docs/whatsapp.md` on day one and never move it.

In M0 you build `tools/wa-api-inventory.sh`, which extracts every exported
symbol (functions, methods, types, constants, event structs) from whatsmeow's
non-test, non-generated Go source, plus every generated protobuf message the
library marshals or unmarshals in non-test code (found by grep for
`proto.Marshal`/`proto.Unmarshal` call sites, then listing the message
types). That inventory is the scope. `tools/wa-coverage.sh` maps each entry
to its C++ counterpart and fails below 100%. `tools/wa-stub-scan.sh` fails
on any of `TODO`, `FIXME`, `XXX`, `HACK`, `unimplemented`, `not implemented`,
`NOT_IMPLEMENTED`, `panic(`, `assert(false`, `std::abort` in
`src/whatsapp/`, and on any new `return std::nullopt` / `return false` /
`return {}` that is not accompanied by a loud log line at the call site.
There is no allowlist file. If you believe something cannot be implemented,
you stop and ask the user; you never stub it and move on.

## 2. Starting point (read all of it)

- `../research/whatsapp-automation/whatsmeow-surface-audit.md`: what exists
  and what is missing at detz 1.46.1.
- `docs/whatsapp.md` (all sections), `docs/cpp-safety.md` (all four layers),
  `AGENTS.md` (the per-milestone workflow), `problem.md`.
- The existing oracle pattern: `tests/whatsapp_data/appstate_oracle.go`
  plus `tests/whatsapp_test.cpp` (run as `build/whatsapp_test`). Extend them,
  do not replace them.

## 3. Milestones and the uniform exit gate

Work the milestone table from the plan (M0..M10) in order. A milestone exits
only when ALL of these hold: spec delta written in `docs/`; code compiles
warning-free under `-std=c++23 -Wall -Wextra -Werror`; Go oracle differential
tests prove every byte behavior (MACs, hashes, encodings, node shapes) with
no hand-written expectations for oracle-computable values; every new or
changed parser ships hostile-input tests plus a sanitizer run
(`-fsanitize=address,undefined -fno-sanitize-recover=all`,
plus the module script pattern of `tools/san-whatsapp.sh`); `make test` is
green; `tools/wa-coverage.sh` reports 100% for the milestone's API slice;
exactly one commit records the milestone. Never let the model grade its own
homework: a test you wrote from your own assumption proves nothing, so every
behavioral claim needs the Go oracle, a golden vector, a live run, or a
second independent method, and every divergence feeds its concrete failing
input back into the fix.

## 4. C++ project law (no deviations)

- One class per `.h`/`.cpp` pair, namespace `detz::wa`, maximally
  object-oriented; headers own their invariants, constructors establish them.
- `docs/cpp-safety.md` Layer 1 in full for every untrusted byte: subtraction
  bounds checks (`len > size - pos`), unsigned range-checked lengths before
  any allocation, guarded shifts and loop bounds, no exception escaping any
  top-level loop, parsing concentrated in the checked readers.
- Every quantity gets a static cap in `wa_consts.h` (rates, sizes, counts,
  intervals); unbounded is a bug. No output file outside `build/`.
- `src/cli/version.hpp` stays generated from `VERSION`; bump per milestone
  group, changelog entry per milestone, annotated tag at the end.

## 5. DRY reuse of moloapp (check before you write)

Before writing any HTTP client, SSE/websocket, LLM provider, config, CLI,
tenancy, or app-pattern code, grep `../../moloapp/src/` (1039 headers;
start with `clients/`, `llm/`, `app/`, `tenancy/` and their `SPEC.md`
files) for an existing facility. Reuse by include plus link only; you never
modify moloapp. Record every reuse decision (used moloapp X / wrote local Y
because Z) in the `docs/whatsapp.md` reuse table you create in M0. A
duplicated facility the library already provides fails review.

## 6. Integration is part of done

Every transpiled capability must be reachable in the working application:
CLI flags where a user would run it, agent tools where the agent would call
it, REPL/UX where it is interactive. A transpiled correct function with no
caller is a stub by another name and fails the M10 gate. Docs state what the
system does on the day, with any live-verification gaps listed next to the
code that will close them.

## 7. Final gate (M10, all must hold)

`make`, `make lint`, `make test` green; `tools/wa-coverage.sh` 100% with
zero unmapped symbols; `tools/wa-stub-scan.sh` zero hits; sanitizer suite
green; live smoke against a linked phone (send, receive, read receipt,
group message, image both directions, contact sync), each recorded with date
in the docs; `CHANGELOG.md`, `VERSION`, annotated tag. Then stop and report:
what shipped, the coverage and test evidence, and anything you were forced
to ask the user, with the answers.

## 8. Working rules

Small diffs, existing files first, no drive-by refactors. Loud skips beat
silent corruption: reject unverifiable input with a reason and a counter.
Never rewrite git history. Never search for or touch grader, oracle-key, or
`.secrets` material; the Go oracles you write yourself from the pinned
whatsmeow source are the only oracles you use.

---

## Recursive validation (prompt vs. every requirement)

| # | Requirement (user's words, condensed) | Prompt section | Verdict |
|---|---|---|---|
| 1 | literally all features, no exception | 1: mechanical inventory of every exported symbol plus every used proto message; 100% gate | covered |
| 2 | no gaps | 1 + 7: coverage script fails below 100%, zero unmapped symbols at the end | covered |
| 3 | no caveats | 1: no allowlist; blocking items stop and ask instead of being waived | covered |
| 4 | validate everything it made itself | 3: oracle differential tests, no-self-grading rule with counterexample feedback; oracle presence per milestone is human-verifiable in review | covered |
| 5 | milestones | 3 + plan table M0..M10 with a uniform exit gate and one commit each | covered |
| 6 | project C++ rules | 4: file layout, OO, cpp-safety Layer 1, static caps, build dir, versioning; enforced by `make lint`, sanitizers, hostile tests | covered |
| 7 | DRY use of moloapp | 5: grep-before-write, link-only, reuse table, duplication fails review (human gate at M10, not a script) | covered |
| 8 | working application at the end | 6: every capability reachable via CLI/tools/REPL; uncalled code fails M10 | covered |
| 9 | zero stubs | 1 + 7: stub scanner patterns, zero-hit gate, no allowlist | covered |
| 10 | online research baked in | Approach + Sources: inventory-plus-verification-script guarantee, oracle/counterexample repair, small-scope strength | covered |
| 11 | saved to `full_transpilation_and_integration.md` | this file | covered |
| 12 | recursively validated | this table: 4 passes (mapping; gate check with 2 human gates labeled; honesty check; re-read), stable with no open items | covered |

Validation passes run: (1) requirement-to-section mapping above; (2) gate
check: every mapped section contains a failing script or command, except rows
4 (no-self-grading discipline) and 7 (moloapp DRY), which are human review
gates, now labeled as such; (3) honesty check: bounded-verification and
live-phone limits are stated in Risks, so no promise outruns its evidence;
(4) re-read after the fixes: paths corrected (`AGENTS.md`, test file), gates
labeled honestly. Stable after pass 4.