feat(contract): add invariant-checked share conversion previews

[arisu6804]

Problem

Callers cannot reliably predict asset/share conversion when rounding, fees, or reserve limits are implicit in the contract.

Objective

Deliver a production-quality improvement to deposit, withdrawal, and share conversion interfaces that creates measurable value for correctness, security, reliability, performance, or maintainability.

Implementation scope

• Expose read-only preview methods for deposit and withdrawal outcomes.
• Use the same fixed-point math and rounding direction as state-changing methods.
• Document and test behavior for zero amounts, minimum units, fees, and max supply.

Acceptance criteria

• Preview results match the corresponding mutation for identical state and input.
• Invalid or dust-sized operations fail with explicit errors.
• Conversion invariants hold across boundary values.

Required validation

• Unit and property tests comparing previews to mutations across randomized balances and rates.
• Existing tests and CI remain passing.
• Add regression coverage for the original failure mode.
• Do not weaken, delete, or skip unrelated tests to obtain a green build.

PR quality bar

• Keep the PR focused on this issue and explain design tradeoffs.
• Include test evidence, compatibility impact, and migration or rollout notes where relevant.
• Avoid typo-only, documentation-only, cosmetic-only, or unrelated refactor submissions.

Out of scope

• Broad rewrites not required by the acceptance criteria.
• Changes to unrelated services, contracts, or user flows.