Add quantum layout for data (#113)

[spital]

Closes #113.

Summary

Adds a padding-free quantum memory layout layer for hhat_core, plus a public
QuantumProgram aggregate for tracking quantum variables, instruction ancilla
qubits, casted quantum attributes, and classical register width needed by later
Q3L lowering/emitters.

The implementation focuses on the reusable layout and accounting layer requested
in #113. It does not claim to complete the full cast-time Q3L lowering pipeline.

What's included

• Maps quantum primitive types to qubit widths (@bool, @u2, @u3, @u4,
  @u8) while keeping those types zero-sized/zero-aligned in the classical
  Cranelift-facing layout.
• Builds quantum struct layouts by stacking quantum member widths with no
  padding.
• Supports nested quantum structs with relative member offsets.
• Supports two-variant quantum enum layouts as one qubit, matching the issue's
  current enum contract.
• Supports static quantum arrays on the direct quantum layout path.
• Converts primitive and struct TypeLayout values into quantum layouts.
• Adds QuantumProgram APIs for variables, quantum instructions, ancilla
  counts, casted attributes, and classical register accounting.
• Documents the classical_registers() double-counting risk at the reader and
  producer call sites.

Design notes

• Quantum layouts are padding-free: classical alignment rules do not add unused
  qubits.
• Classical fields inside quantum structs do not consume qubits and do not shift
  quantum offsets.
• classical_registers() intentionally counts one classical register bit per
  measured qubit recorded through casted attributes or explicit instruction
  registers. Callers should record each measured qubit through one path.
• Enum and array TypeLayout integration is scaffolded around the current
  LayoutCache limitations. The direct quantum layout cache already supports
  two-variant enums and static arrays.

Testing

• cargo test -p hhat_core - 13 passed, doctests passed.
• cargo test --workspace --exclude hhat_lang - all tests passed.
• RUSTDOCFLAGS='-D rustdoc::broken_intra_doc_links' cargo doc -p hhat_core --no-deps - passed.

Coverage includes primitive quantum widths, simple and nested quantum structs,
two-variant quantum enums, static arrays, mixed classical/quantum structs,
TypeLayout conversion, casted classical registers, and ancilla sweeps from
0 through 3.

Out of scope / known existing issues

• cargo test -p hhat_lang still fails on the pre-existing hardcoded fixture
  path assertion in src/ir/project.rs:241.
• cargo clippy -p hhat_core still reports 8 pre-existing warnings in
  layout/adt.rs and layout/base.rs; none are in the new quantum layout
  module.
• The current Rust crate has broad pre-existing rustfmt drift. This PR avoids
  unrelated formatting churn.

Follow-up work after this lands

• Wire the quantum layout/accounting layer into the later cast-time Q3L lowering
  path.
• Extend enum/array TypeLayout conversion once the classical LayoutCache
  exposes the needed enum/array layout information.
• Clean up pre-existing classical-layout clippy/rustfmt drift in a separate PR.

Generative AI/LLM disclosure

I used AI coding assistants, including Hermes, Claude Code, and Codex, while
preparing this PR. They helped with codebase exploration, implementation and test
drafts, iterative review, verification checklists, and PR-description drafting.

I reviewed the final diff and am responsible for the submitted changes. The local
verification I am relying on is listed in the Testing section above, and the known
pre-existing failures/warnings are listed separately rather than hidden.

Code and Logic Architecture/Design:

• The code and logic architecture/design contain no generative AI/LLM
• The code and logic architecture/design are partially performed by generative AI/LLM
  • X% performed by the author(s)
• The code and logic architecture/design are fully performed by generative AI/LLM

Code content:

• The code contains no generative AI/LLM work
• The code is partially written by generative AI/L
  • X% performed by the author(s)
• The code is fully written by generative AI/LLM

Code review:

• The code review contains no generative AI/LLM
• The code review is partially done by generative AI/LLM
  • ?% performed by the author(s)
• The code review is fully done by generative AI/LLM

Code tests:

• The code tests contain no generative AI/LLM
• The code tests are partially written by generative AI/LLM
  • X% performed by the author(s)
• The code tests are fully written by generative AI/LLM

[Doomsk]

Hi @spital thank you for the PR. However, according to this repo AI policy, it's not allowed to have fully AI generated code and the author is responsible for what it ships.

Let me know whether there are questions before I will close this PR.

[spital]

Hi Doomsk,

Thank you for taking the time to comment.

I understand and respect the repository policy. I also understand that, regardless of what tools I used while working on this, I am responsible for the code I submit and for anything it ships.

This PR was not a "spray and pray" submission. I spent a lot of time getting it to this state, reviewing the changes, testing them, and trying to make sure the result is useful to the project. I believe the PR is still worth a technical review, but I respect your decision either way.

My motivation here is simply to contribute something valuable to open source while I am looking for paid remote work. I do not have any questions at this point. If you are curious about how I approached the work, feel free to ping me here or on the unitaryhack-26 Discord and I would be happy to chat.

Thanks again.

[Doomsk]

Ping me there: @Doomsk

[spital]

Dear maintainers,

I am sorry, but I need to close this PR for now.

This is not because I am withdrawing the technical work or because I no longer want to contribute. I recently learned that the unitaryHACK limit is no more than four open pull requests at one time, and I misunderstood that rule when I opened this PR. I apologize for creating extra review burden.

Recent upstream commit created a conflict to my branch and I have not received maintainer feedback on this PR, and I do not want to keep it open while I am over the event limit. I will therefore close it voluntarily. If the limit or timing later allows, I would be happy to continue working on this issue, reopen the PR, or prepare a fresh branch based on the maintainer's preferred direction. Please do not hesitate to ping me here or on the unitaryHACK 2026 Discord.

Thank you for your time, and sorry again for the inconvenience.

Kind regards.