# Cleanup 04 — Circular Import / Dependency Cycles

Agent 04 of 8. Scope: cycles introduced or worsened by this session in `CLEANUP_SCOPE.md` files. Tooling: manual `rg`/`grep` over `^import` lines (madge n/a for this Nim/Rust/C++ stack).

## Research notes — import graph of in-scope clusters

### Cluster A — `waku_mix/logos_core_client.nim` ↔ plugin

```
logos_core_client.nim
  -> mix_rln_spam_protection/group_manager   {.all.}
  -> mix_rln_spam_protection/types           {.all.}
  -> mix_rln_spam_protection/rln_interface
  -> mix_rln_spam_protection/onchain_group_manager   (NEW: re-exports ExternalMerkleProof)

mix_rln_spam_protection/onchain_group_manager.nim
  -> ./types  ./constants  ./rln_interface  ./group_manager
  (zero references to waku_mix / nwaku / logos-chat)

mix_rln_spam_protection/{group_manager,types,rln_interface}.nim
  -> only sibling plugin modules + std/chronos/results/chronicles/stew
```

`rg 'logos_core_client|waku_mix' vendor/nwaku/vendor/mix-rln-spam-protection-plugin/` → 0 hits.

### Cluster B — `rln_gifter/` four-file cluster

```
rpc.nim         -> std/options                              (leaf)
rpc_codec.nim   -> std/options, ../../common/protobuf, ./rpc
protocol.nim    -> std/[options,sets], chronos/results/..., ../../node/peer_manager/peer_manager,
                   ../../waku_core, ./rpc, ./rpc_codec
client.nim      -> std/options, results, chronos, bearssl/rand, libp2p/stream/connection,
                   ../../node/peer_manager, ../../waku_core, ../../utils/requests, ./rpc, ./rpc_codec
```

Topological order: `rpc` < `rpc_codec` < {`protocol`, `client`}. `protocol` and `client` are siblings; neither imports the other. Strict DAG.

### Cluster C — callers of the new symbols

```
node_factory.nim   -> logos_core_client (alias mix_lez_client)
                   -> mix_rln_spam_protection/onchain_group_manager  (direct)
                   -> rln_gifter/protocol, rln_gifter/client          (direct)

src/chat/delivery/waku_client.nim
                   -> waku/waku_mix/logos_core_client as mix_lez_client
                   -> waku/waku_rln_relay/rln_gifter/{client,protocol}
                   -> mix_rln_spam_protection/{onchain_group_manager,rln_interface,spam_protection}
```

Both callers use `OnchainLEZGroupManager`, `FetchRootsCallback`, `FetchProofCallback`,
`MembershipIndex` via the `onchain_group_manager.X` qualifier. The direct plugin import is
necessary, not redundant with the `logos_core_client` re-export (which only re-exports
`ExternalMerkleProof`).

## Critical assessment

| Candidate                                                                                                   | Verdict   | Reason |
|-------------------------------------------------------------------------------------------------------------|-----------|--------|
| `logos_core_client` -> `onchain_group_manager` -> ... -> `logos_core_client`                                | SPURIOUS  | Plugin has zero references to nwaku/waku_mix. Forward edge only. |
| Plugin's `onchain_group_manager` reaching back into nwaku via new accessors (proofRoot/getPollInterval)     | SPURIOUS  | New procs operate on plugin-local state and types; no nwaku imports added. |
| rln_gifter `protocol` <-> `client` mutual import                                                            | SPURIOUS  | Neither imports the other; both depend only on `rpc`/`rpc_codec`. |
| rln_gifter `rpc_codec` <-> `rpc`                                                                            | SPURIOUS  | `rpc_codec` -> `rpc` only; `rpc.nim` imports only `std/options`. |
| `node_factory` importing both `mix_lez_client` and `onchain_group_manager` (redundant?)                     | SPURIOUS  | Caller uses multiple plugin-only symbols; re-export covers only `ExternalMerkleProof`. |
| `waku_client.nim` (outer) similar dual import                                                               | SPURIOUS  | Same reason as node_factory. |
| "typed as pointer to break a cyclic import" workaround marker (logos_core_client.nim:53)                    | OBSOLETE COMMENT | The pointer is the FFI callback ABI to C++ (`setGroupManagerRef(gm: pointer)`); cycle is no longer the real reason. Plugin doesn't import logos_core_client, so a typed ref *would* compile. But the opaque `pointer` is correct as an FFI boundary type; only the comment is misleading. |

## Recommendations

1. No real cycles to break. Import graph in scope is a clean DAG.
2. (Doc-only, deferred) Re-word `logos_core_client.nim:53` comment from "typed as pointer to break a cyclic import" to "typed as opaque pointer for the C++ FFI callback boundary". Strictly cosmetic; not worth a commit churn on this load-bearing file during cleanup pass. Suggested for whoever next edits that region.
3. The `ExternalMerkleProof` re-export from `logos_core_client` is genuinely useful for downstream consumers that don't already need the broader `onchain_group_manager` surface — but both current callers (`node_factory`, outer `waku_client`) need the broader surface anyway and can drop reliance on the re-export. Not worth changing; the re-export is harmless.

## Applied

No code changes. Mirrors verified byte-identical post agents 01-03:

```
3c3bd2e20ffa315e37a9c86c2002f8bbe5095e5e33e1df7c805cc41db5552d4c  vendor/nwaku/waku/waku_mix/logos_core_client.nim
3c3bd2e20ffa315e37a9c86c2002f8bbe5095e5e33e1df7c805cc41db5552d4c  vendor/logos-lez-rln/logos-delivery/waku/waku_mix/logos_core_client.nim
3c3bd2e20ffa315e37a9c86c2002f8bbe5095e5e33e1df7c805cc41db5552d4c  vendor/logos-lez-rln/logos-delivery-module/vendor/logos-delivery/waku/waku_mix/logos_core_client.nim
```

Re-validation after agents 01 (`bytesToHexUpper` extraction), 02 (type
consolidation no-op), and 03 (drop dead `hexToBytes32LE` + stale imports):

- Plugin (`mix-rln-spam-protection-plugin/`) still has zero references to
  `logos_core_client` / `waku_mix` — agents 01/03 only touched the nwaku
  side, never the plugin side. Edge direction preserved.
- `rln_gifter/` four-file cluster topology unchanged: `rpc` < `rpc_codec`
  < {`protocol`, `client`} remains a clean DAG; no sibling cross-import.
- Agent 03's unused-import removals (`std/sequtils` from `protocol.nim`,
  `waku_peer_store` from `protocol.nim`, `sharding` from
  `waku_mix_coordination.nim`, `std/algorithm` from `logos_core_client`)
  only reduce dependency surface — none introduced a new edge.
- C++ header graph: `liblogos_rln_module_api.h` (chat-module +
  delivery-module + logos-rln-module copies) includes only outward-facing
  `logos_api*.h` / `logos_mode.h` / `logos_object.h`. No back-edges from
  any included header to its consumers. Plugin source files form the
  expected unidirectional chain `*_plugin.cpp -> *_plugin.h ->
  *_module_interface.h -> interface.h`. Clean DAG.

Updated note also retracts the prior deferred "comment rewording at
`logos_core_client.nim:53`" item — the live file's comment (lines 53-57)
already explains the `pointer` as a cross-thread GC isolation
workaround, not a cycle workaround. Stale wording already gone.

No commits at any of the 5 repo levels.

## Deferred

- None. `madge` not applicable to Nim/Rust/C++ stack; manual `^import` /
  `^#include` survey across the in-scope file set is sufficient and was
  run twice (initial pass + post-01/02/03 re-validation).