logos-delivery/docs/analysis/plan_phase1_bench.md

# Phase 1 — Message-path performance benchmark (executor plan)

> Self-contained implementation plan. Context: [async_copy_analysis.md](async_copy_analysis.md)
> and [async_copy_fix_plan.md](async_copy_fix_plan.md). Read both before starting.
>
> **Objective**: a reproducible before/after benchmark of the WakuMessage inbound/outbound
> pipeline, plus decode/hash counters that verify the analysis claims (≥4 decodes and 4–6
> SHA-256 passes per inbound relayed message on the current code). This phase changes **no
> production behavior** — counters must compile to nothing without the define.

## Constraints (apply to all phases)

- Nim 2.2.4, `--mm:refc` (enforced by nimble tasks). Build via `make` / nimble tasks only.
- Format all touched files with nph (`make nph/<file>` or the pre-commit hook).
- Run `gitnexus_impact` before editing cross-module symbols and `gitnexus_detect_changes()`
  before committing (project rule in AGENTS.md). Commit at the end of the phase; **never push**.
- Verify claims by running things, not by reasoning ("should work" is not done).

## Existing infrastructure to reuse

- `apps/benchmarks/benchmarks.nim` — existing RLN benchmark; nimble task at
  `logos_delivery.nimble:391-393` (`task benchmarks` → `buildBinary name, "apps/benchmarks/"`).
  Mirror this pattern; note it already imports from `tests/` (`tests/waku_rln_relay/utils_onchain`),
  so importing `tests/testlib/*` from `apps/benchmarks/` is accepted practice.
- `tests/testlib/wakucore.nim` — `fakeWakuMessage*` (line ~74) for deterministic messages.
- `tests/testlib/wakunode.nim` (verify exact name) — node construction helpers used by all
  node tests; use these for the macro scenario.

## Step 1 — Instrumentation counters (`-d:msgPathCounters`)

New file `logos_delivery/waku/waku_core/message/path_counters.nim` (~35 LOC):

```nim
when defined(msgPathCounters):
  type MsgPathCounters* = object
    decodeCalls*, hashCalls*: int64
    decodedBytes*, hashedBytes*: int64
  var msgPathCounters* {.global.}: MsgPathCounters
  template countDecode*(bytes: int) = ...   # inc calls, add bytes
  template countHash*(bytes: int) = ...
  proc resetMsgPathCounters*() = ...
else:
  template countDecode*(bytes: int) = discard
  template countHash*(bytes: int) = discard
```

Hook points (one line each, guarded template — zero cost when undefined):
- `logos_delivery/waku/waku_core/message/codec.nim:23` — inside
  `proc decode*(T: type WakuMessage, buffer: seq[byte])`: `countDecode(buffer.len)`.
- `logos_delivery/waku/waku_core/message/digest.nim:53` — inside `computeMessageHash`:
  `countHash(msg.payload.len + msg.meta.len)`.

Export via `waku_core` module as needed. Single-threaded chronos — plain int64, no atomics.

## Step 2 — Micro benchmark (in-process pipeline, no network)

New file `apps/benchmarks/message_path_bench.nim` (~250–320 LOC total with Step 3).

Setup: one WakuNode with relay mounted + archive (SQLite **in-memory** driver) + store-sync
(reconciliation) mounted; subscribe one shard so `registerRelayHandler`
(`logos_delivery/waku/node/subscription_manager.nim:29`) installs the full
`uniqueTopicHandler` chain (trace/filter/archive/sync/internal handlers, :45-82).

Injection: per message, replicate the gossipsub inbound sequence using WakuRelay's own
registered artifacts (both are stored in public tables on `WakuRelay`,
`waku_relay/protocol.nim:624,632`):
1. `let data = msg.encode().buffer` (prepared up front, excluded from timing)
2. `discard await relay.topicValidator[shard](shard, Message(topic: shard, data: data))`
   — exercises the ordered-validator decode (`protocol.nim:543`)
3. `await relay.topicHandlers[shard](shard, data)` — exercises topicHandler decode
   (`protocol.nim:603`) + full dispatch chain

Note in the output that observer decodes (`protocol.nim:271,326,341`) are NOT exercised by
the micro bench (they fire only in real gossipsub dispatch) — the macro scenario covers them.
If `topicValidator`/`topicHandlers` turn out not to be exported, add a
`when defined(msgPathCounters)` accessor to `waku_relay/protocol.nim` rather than exporting
the fields unconditionally.

Workload: fixed-seed generator (xorshift or `std/random` with `randomize(42)` equivalent —
NO time-based seed), payload mix **10 kB / 50 kB / 150 kB at 25 % / 50 % / 25 %**, unique
timestamps/nonce per message (avoid dedup), N = 1,000 messages + 100 warmup (excluded).

## Step 3 — Macro benchmark (two nodes, loopback gossipsub)

Same file, second scenario: two in-process nodes (testlib helpers), connected, both
subscribed to the shard; node B additionally has archive + sync mounted. Node A publishes
the same workload; node B counts arrivals via an app handler; stop timing when all N
received (with a sane timeout). This path includes libp2p rpcHandler + observers, so
counters here should show the full ≥4 decodes/message.

## Step 4 — Metrics & output

Per scenario emit one human block + one machine-readable CSV line to stdout:

```
scenario,msgs,payload_profile,wall_ms,msg_per_s,ns_per_msg_p50,ns_per_msg_p99,
decodes_per_msg,hashes_per_msg,hashed_MB,decoded_MB,occupied_mem_delta_MB,gc_collections
```

Sources: `getMonoTime` deltas per message for p50/p99; `getOccupiedMem()` before/after;
refc `GC_getStatistics()` (print raw string); counters from Step 1 (reset between scenarios).

## Step 5 — Build task + baseline capture

- Add nimble task `benchMessagePath` to `logos_delivery.nimble` mirroring the existing
  `benchmarks` task (:391-393), with `-d:msgPathCounters` added to its flags.
- Run it on the **current branch before Phases 2/3**; save both scenario outputs verbatim
  into `docs/analysis/bench_baseline.md` with the commit hash and machine info
  (`sysctl -n machdep.cpu.brand_string`, macOS version).

## Acceptance criteria

1. `make test` still fully green (production code untouched except no-op templates).
2. A production build **without** `-d:msgPathCounters` compiles and the counter templates
   vanish (verify: `nim c` of wakunode2 target still succeeds).
3. Two consecutive micro runs differ by < 5 % on msg/s (determinism check).
4. Macro scenario counters confirm the analysis: `decodes_per_msg ≥ 4`,
   `hashes_per_msg` in 4–6 on the receiving node. **If not, STOP and report the measured
   numbers before proceeding to Phase 2 — the analysis (and the expected gains) must be
   recalibrated first.**
5. `docs/analysis/bench_baseline.md` committed with the numbers.

## Estimated diff

~370–480 new LOC, ~10 changed LOC, no behavior change. Budget: 1–1.5 days.