The coordination harness is test-only: the documented multi-contract scenarios cannot be exercised against the real contract

[usmanimamu17-create]

Problem

src/coordination_harness.rs is a #[cfg(test)] module (its only content is mod coordination_harness_tests) documenting six scenarios — clean deployment, staged upgrade, incompatible rollback, correlation across boundaries, paused-in-group, safety rollback — and testing them against build_negotiation_info/negotiate_contract_versions/CrossContractSafety directly. No contract method exposes negotiation or safety (companion issues), so the harness exercises the libraries, not the deployed contract.

Consequences:

• The scenarios certify library functions, not the contract: a regression in get_version_info's real response (e.g. the VersionInfo shape) would not fail any harness scenario, because the harness never calls it.
• The documented multi-contract guarantees are unverifiable on-chain: "Staged upgrade" and "incompatible rollback" are the exact situations operators face during deployment, but the only thing that can be run is a unit test over in-memory structs.
• The harness creates false confidence: CI passing on these scenarios suggests the deployment story is validated when the real integration surface is untested.

Root cause

The harness was written as unit tests for the library modules before the contract surface exposed them; the "integration" framing in the module doc outran the wiring.

Why this is architecturally hard

1. Making the scenarios exercise the real contract requires the negotiation/safety/correlation surfaces to be exposed (companion issues) — or, failing that, requires the harness to be re-scoped as a pure library test and the module doc corrected.
2. True multi-contract testing needs multiple registered contracts in one Env (Soroban supports this) with the SLA calculator actually invoking peers — which the safety wiring (companion issue) has not landed.
3. The deliverable here is partly documentation: a clear statement of what is tested (libraries) vs. what is not (deployed multi-contract flows), plus a migration path to real integration tests.

Acceptance criteria

• The module doc states the harness's actual scope (library-level vs. contract-level).
• Each scenario that can be run against the real contract surface is run that way; others are explicitly marked future-facing.
• CI output distinguishes library tests from integration scenarios.

Out of scope

Wiring negotiation/safety/correlation into the contract (companion issues) and building the escrow peer.

Getting started

just test

Good first files to read: apexchainx_calculator/src/coordination_harness.rs, apexchainx_calculator/src/version_negotiation.rs.

[divysam]

@divysam has applied to work on this issue as part of the Stellar Wave Program's 8th wave.

Hello
I would love to work on this issue please

ℹ️ Repo Maintainers: To accept this application, review their application or assign @divysam to this issue.

[Rayyanah0]

@Rayyanah0 has applied to work on this issue as part of the Stellar Wave Program's 8th wave.

Hi Maintainer, I would like to work on this issue because I understand the problem and have a clear approach to solving it. Please assign to me.

ℹ️ Repo Maintainers: To accept this application, review their application or assign @Rayyanah0 to this issue.

[m-hajjo]

@m-hajjo has applied to work on this issue as part of the Stellar Wave Program's 8th wave.

I have read the requirements of this issue and i am confident that i can solve this

ℹ️ Repo Maintainers: To accept this application, review their application or assign @m-hajjo to this issue.

[felladaniel36-hash]

@felladaniel36-hash has applied to work on this issue as part of the Stellar Wave Program's 8th wave.

can i please work on this ?

ℹ️ Repo Maintainers: To accept this application, review their application or assign @felladaniel36-hash to this issue.

[drips-wave]

Congratulations, @m-hajjo! 🎉 Your application was accepted by the repo's maintainers, and the issue is due on August 31, 2026.

🧑‍💻 @m-hajjo: Please resolve the issue such that the repo's maintainers have enough time to review your contribution before the due date. You'll earn Points for completing the issue on-time, which will make you eligible for a share of the Stellar Wave Program's reward pool.

Warning

When opening a PR, please link it to this issue to ensure it gets tracked accurately. Points are awarded when this issue is marked as completed by the maintainer.

🤠 Repo maintainers: Please keep an eye on the contributor's progress and review their work before the due date. You can manage this issue, including adjusting its complexity and points, here.

🌊 Happy Wave 🌊

[grantfox-oss]

🎉 This issue has been marked as completed on GrantFox!

@m-hajjo's PR #556 was approved and merged by @usmanimamu17-create.

🏆 @m-hajjo: You earned 35 FoxPoints for this contribution! Your current tier: Explorer (872 total points). Track your full progress on GrantFox.

👏 Great work, @m-hajjo! Keep contributing to ApexChainx.