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.