Clarify sparse pyQuil unitary errors

[Sanjays2402]

Closes #1287

Summary of changes

Sparse pyQuil programs now fail before pyQuil's low-level permutation logic and explain both supported qubit-compaction options. The regression test fails with Permutation SWAP index not valid before the fix and passes with the actionable error; all 8 focused pyQuil program tests and Ruff checks pass.

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: d0937f09-5b8a-4260-9660-56648d2fc614

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}