Prefer SymPy built-ins over custom math plumbing

[sacchen]

Use SymPy-native APIs for core math behavior where we currently hand-roll logic, while preserving phil safety and UX contracts.

Goal

Reduce custom math plumbing in core internals to lower correctness risk and maintenance overhead.

Scope

1. Simplification policy

• Replace unconditional broad simplify() in src/calc/core.py with a targeted pipeline using SymPy primitives where intent is clear (cancel, together, trigsimp, powsimp, etc.).
• Preserve --no-simplify behavior.

2. Matrix solve internals

• Migrate msolve / linalg solve internals toward SymPy matrix-native solve APIs (A.solve(b) family) instead of hardwiring a single method.
• Keep existing UX errors/hints for bad shapes/inputs.

3. Assumption-sensitive behavior

• Use SymPy assumptions/refinement APIs for selected domain-sensitive paths.
• Keep conservative behavior when assumptions are unknown.

Out of Scope

• Onboarding/help/tutorial UX work (Improve docs: onboarding, design philosophy, and roadmap #5).
• New feature families (Define CS/applied-math feature track (excluding #1/#4) #3, Add exact-first stats/probability helper surface #4) beyond implementation guidance.
• Parser safety model changes (GLOBAL_DICT, blocked tokens, input limits).

Relationship to Other Issues

• Complements Edge-case reliability: correctness, fast answer, fast recovery #7 (edge-case reliability).
• Informs implementation style for Add exact-first stats/probability helper surface #4 and Define CS/applied-math feature track (excluding #1/#4) #3.
• Prioritized via Umbrella: prioritize math branch roadmap across feature tracks #6 roadmap umbrella.

Acceptance Criteria

• Scoped internals are SymPy-backed rather than custom algebra logic.
• Existing CLI UX remains intact (E: + hint: quality).
• One-shot and REPL parity maintained.
• Tests added for each user-visible behavior change.

Validation Gate

• uv run --group dev pytest
• uv run --group dev pytest --cov=calc --cov-report=term-missing --cov-fail-under=90

[sacchen]

Related issues for planning and execution:

• Umbrella: prioritize math branch roadmap across feature tracks #6 (umbrella prioritization): this issue proposes internal implementation direction that should be ranked in now/next/later.
• Edge-case reliability: correctness, fast answer, fast recovery #7 (edge-case reliability): this issue provides a mechanism to improve correctness/fast recovery by using more SymPy-native behavior.
• Add exact-first stats/probability helper surface #4 (stats/probability): explicitly recommends for implementation in that track.
• Define CS/applied-math feature track (excluding #1/#4) #3 (CS/applied math): relevant if matrix/discrete helpers expand and should stay SymPy-backed where possible.

[sacchen]

Correction to prior comment: for #4, the recommended implementation base is sympy.stats (no manual PMF/CDF formula plumbing where avoidable).

[sacchen]

Linked strategy anchor: #9 (Product principles and design decision framework).\n\n#8 implementation choices should follow #9 policy on predictability, small coherent slices, and reliability gates.

[sacchen]

Carry-over note from pre-release final review:

Before/while doing #8 internals cleanup, include these small hardening tasks:

1. In src/calc/core.py, avoid log shadowing between math.log and sympy.log in growth-guardrail numeric checks.
   • Current state works, but guardrail threshold code should use an explicit math alias for clarity and stability.
2. Keep guardrail behavior/tests unchanged while doing the above (huge power/tower/factorial fail-fast + cancellation fast path).

Why track this here:

• Prefer SymPy built-ins over custom math plumbing #8 is the right place to tighten internal math plumbing and remove subtle implementation risks without changing user-facing semantics.