feat(lesson15): Added CoinJoin heuristics lesson

[Av1ralS1ngh]

Summary

Adds Lesson 15 as an interactive educational flow focused on practical transaction pattern analysis. The lesson covers CoinJoin-style outputs, a normal multi-party baseline, and a direct comparison between the two, with heuristic thresholds and interpretation guidance.

---

What Changed

Lesson flow (src/my_tx_flows/p15_CoinJoin_Equal_Output_Heuristics.json)

• Three-part interactive flow: CoinJoin, Normal Baseline, Comparison
• Threshold-based heuristic checks for anonymity set and equal-output ratio
• Interpretation guidance clarifying these are heuristic signals, not proof

Backend (backend/calc_functions/calc_func.py, backend/calc_functions/function_specs.py, backend/graph_logic.py)

• Added CoinJoin metrics: denomination detection, anonymity set count, change-output count, equal-output ratio, and summary report
• Wired Lesson 15 helper functions into graph execution

Flow registration (src/my_tx_flows/customFlows.ts)

• Registered Lesson 15 in the flow catalog

Docs (README.md, docu/l-sum.md)

• Updated project docs to include Lesson 15

---

Testing and Validation

• Added and updated targeted backend helper tests in backend/tests/test_calc_func.py
• Added and updated backend roundtrip coverage in backend/tests/test_flow_roundtrip.py
• Added and updated flow listing validation in backend/tests/test_routes.py
• Added and updated E2E roundtrip coverage in tests/e2e/flow.roundtrip.spec.ts
• Stabilized E2E flow loading utility in tests/e2e/utils.ts
• Verified Lesson 15 scenario with targeted Playwright execution

---

Out of Scope

This PR covers educational heuristics and comparison logic only. Full CoinJoin protocol simulation and advanced wallet fingerprinting are intentionally out of scope for this iteration.

[rawBit-io]

For me this is still not really a CoinJoin lesson yet, it reads more like a CoinJoin heuristics tool. But as proof of work / competency check, I think it is still useful.

A complete rawBit CoinJoin lesson, as I imagine it, should start from real tx groups and build toward a real CoinJoin tx, with the tx relationships visible directly on the canvas / protocol map. Ideally it would show a few examples in progression — starting from a simple case and then moving to a more complex one with likely change outputs or false positives. Heuristics like equal outputs, likely change outputs, anonymity-set intuition etc can then support the explanation, but they should not be the center of the lesson.

So overall, as proof of work for Summer of Bitcoin 2026 application I think this is good.

[Av1ralS1ngh]

Heads up! the work and wiring has some rough edges which I will clean up in the following commit soon :)

I have proceeded and implemented my first iteration of the complete CoinJoin lesson in accordance to your vision.
The flow now progresses through three explicit examples: a simple clean baseline, a realistic multi-party round with change outputs, and a strong false-positive case.

I added on-canvas protocol relationship checks for each case (independent input owners and parent transaction diversity) and wired those gates into case verdicts and cross-case comparison, so transaction relationships are directly visible and actually drive conclusions.
As discussed, heuristics such as equal outputs, change behavior, and anonymity-set signals are still included, but now as supporting evidence rather than the center of the lesson.
I also tightened the explanatory layout and graph wiring for clearer reading and more reliable node evaluation.

Please review at your convenience.

[rawBit-io]

PR #2 fails to run because @/lib/flow/overlap is imported in:

• src/hooks/useNodeOperations.ts
• src/hooks/useCopyPaste.ts

…but src/lib/flow/overlap.ts is missing from this branch.

Please add that file (or update the import path if it was renamed).

[Av1ralS1ngh]

oh yes apologies! I have just added that file back in.
Everything should work correctly now.
Thanks!

[rawBit-io]

thanks for another update and for putting more work into this.

But for me this is still going in wrong direction. I asked for lesson which starts from complete tx and then builds real CoinJoin tx from them, with script validation and sent to testnet. Instead this is still mainly classification / analytics flow.

Also from rawBit design side this still does not match how rawBit flows are built. I normally do not pack comma-separated inputs into one field, and also not several values into one output. Normally one field = one input, and when something branches we use explicit nodes with multiple output handles.

I also still do not see real grouping / flow-map logic here, and for this kind of lesson this part is important.