Add CachedCBig, the cache-backed variant of CBig

CachedCBig is the complex twin of CachedFBig: it wraps a CBig plus a shared
Rc<RefCell<ConstCache>> handle and threads it through the complex
transcendentals (ln/exp/powf/sin/cos/tan/sin_cos/asin/acos/atan/arg),
reusing ConstCache unchanged — CBig's transcendentals are built entirely
from real FBig ops, so there are no complex-specific constants to cache.

It mirrors CBig's full always-on trait surface (formatting, ordering,
conversions, the binary operators incl. cross-type ops against both CBig
and FBig, Neg/Inverse, Sum/Product), is !Send + !Sync (so CBig stays
Send + Sync and static_cbig! is unaffected), and ships under the
dashu::FastComplex alias. The forward-compatible cache: Option<&mut
ConstCache> hook (convenience layer passes None, cached layer passes Some)
meant no Context signature change was needed.

Two intentional divergences from CBig: into_parts returns (CachedFBig,
CachedFBig) sharing the handle (vs CBig's (FBig, FBig)), and there are no
ZERO/ONE/I constants (Rc isn't const-constructible). Third-party traits
(serde/num-traits/num-order/num-complex/rand) are intentionally not
mirrored — reach them via .as_cbig().

Operator surface is macro-driven, mirroring fbig_cached_ops.rs. Tests live
as #[cfg(test)] mod tests blocks in the two source files (split by what
each owns), matching the CachedFBig layout.

Also updates AGENTS.md (cached-wrappers rule now covers CachedCBig +
FastComplex), TODO-v05.md (pulled forward from §3.4 into the Phase 3
"implemented" status), the complex changelog, and the guide's cached page
plus its SUMMARY title.

Co-Authored-By: Claude <noreply@anthropic.com>

Author: Jacob Zhong

AGENTS.md

@@ -82,7 +82,7 @@ Keep the `## Unreleased` section updated as you go.
 
 ## Cached wrappers (`CachedFBig`, `CachedCBig`)
 
-**`CachedFBig` is a drop-in replacement for `FBig`, and `CachedCBig` for `CBig`.** Each cached wrapper must mirror the full public API and trait surface of its non-cached counterpart, delegating every impl to the inner value. **Whenever you add or change a trait impl on `FBig` or `CBig`, mirror it on `CachedFBig` / `CachedCBig` in the same change** — otherwise the `FastReal` / `FastDecimal` aliases regress: code that compiles with `FBig` must compile unchanged with `CachedFBig`. The only intentional divergences are that the cached type's transcendental ops thread the shared `ConstCache`, it is `!Send + !Sync`, construction takes a cache handle, and **third-party crate traits (serde, num-traits, num-order, rand, zeroize, postgres/diesel) are intentionally not mirrored** — reach them through `.as_fbig()` / `.as_cbig()`. (`CachedCBig` is planned but not yet implemented — this rule applies once it lands.)
+**`CachedFBig` is a drop-in replacement for `FBig`, and `CachedCBig` for `CBig`.** Each cached wrapper must mirror the full public API and trait surface of its non-cached counterpart, delegating every impl to the inner value. **Whenever you add or change a trait impl on `FBig` or `CBig`, mirror it on `CachedFBig` / `CachedCBig` in the same change** — otherwise the `FastReal` / `FastDecimal` / `FastComplex` aliases regress: code that compiles with `FBig`/`CBig` must compile unchanged with `CachedFBig`/`CachedCBig`. The only intentional divergences are that the cached type's transcendental ops thread the shared `ConstCache`, it is `!Send + !Sync`, construction takes a cache handle, `CachedCBig::into_parts` returns `(CachedFBig, CachedFBig)` sharing the handle (not `CBig`'s `(FBig, FBig)`), and **third-party crate traits (serde, num-traits, num-order, rand, zeroize, postgres/diesel) are intentionally not mirrored** — reach them through `.as_fbig()` / `.as_cbig()`.
 
 ## dashu-int internals
 

TODO-v05.md

@@ -207,6 +207,16 @@ the primary `Real`/`Decimal`.
 > `Context`). Verified with proptest identities + self-oracles, deterministic Annex-G vectors, and a
 > manual `rug::Complex`/MPC oracle in `fuzz/`. `NumHash` mirrors `num-complex`'s `Complex<f64>`
 > algebraic hash (verified against the `num-order` reference). See `complex/CHANGELOG.md` (0.5.0).
+>
+> **`CachedCBig`** — the cache-backed variant mirroring `CachedFBig` (originally listed in §3.4) has
+> been implemented and pulled into 0.5. It wraps a `CBig` plus a shared `Rc<RefCell<ConstCache>>`
+> handle, threads it through the complex transcendentals (`ln`/`exp`/`powf`/`sin`/`cos`/`tan`/`sin_cos`/
+> `asin`/`acos`/`atan`/`arg`) — reusing `ConstCache` unchanged, since `CBig`'s transcendentals are built
+> entirely from real `FBig` ops — mirrors `CBig`'s always-on trait surface (it is `!Send + !Sync`, so
+> `CBig` stays `Send + Sync` and `static_cbig!` is unaffected), and ships under the `dashu::FastComplex`
+> alias. The forward-compatible `cache: Option<&mut ConstCache>` hook (convenience layer passes `None`,
+> cached layer passes `Some`) meant no `Context` signature change was needed. See `complex/CHANGELOG.md`,
+> `complex/src/cbig_cached.rs`, and `guide/src/cached.md`.
 
 **Goal:** a new crate `dashu-cmplx` (dir `complex/`) providing an arbitrary-precision complex type
 `CBig`, targeting GNU MPC parity for "common functionalities." It composes two parts (`re`, `im`)
@@ -281,14 +291,6 @@ removed). All additive — safe as point releases under 0.5.x.
   parts).
 - **A `ComplexFloat`-style trait** unifying `FBig` and `CBig` (sealed, for generic real/complex code).
 - **Ball arithmetic** (the `mpcb_t` analogue — interval/uncertainty complex).
-- **`CachedCBig`** — a cache-backed variant mirroring `CachedFBig`. Its structure is settled (so 0.5
-  is forward-compatible): it wraps a `CBig` plus a shared `Rc<RefCell<dashu_float::ConstCache>>`
-  handle, reusing `ConstCache` unchanged from `dashu-float` (there are no complex-specific constants
-  to cache — `CBig`'s transcendentals are built entirely from real `FBig` ops). `CachedCBig` is
-  `!Send + !Sync` while `CBig` stays `Send + Sync` (so `static_cbig!` produces `CBig`). **This is why
-  0.5 already threads `cache: Option<&mut ConstCache>` through the transcendental `Context` ops:** the
-  convenience layer passes `None`, `CachedCBig` will pass `Some(&mut cache)`, so adding the cached
-  variant needs no signature change.
 - **Expose ownership-aware kernel functions from `dashu-float`** — `dashu-float`'s `add.rs` already
   has `add_val_val` / `add_val_ref` / `add_ref_val` / `add_ref_ref` kernel functions that consume
   owned `FBig`/`Repr` when available (avoiding unnecessary clones at the convenience layer). These are
@@ -391,8 +393,9 @@ removed). All additive — safe as point releases under 0.5.x.
 
 - `dashu-python` remains excluded and out of the release critical path (per `AGENTS.md`).
 - All `dashu-cmplx` follow-ups (complex hyperbolics, `fma`, `rootofunity`, `agm`, Ziv correct
-  rounding, `CBig` serde/rkyv/zeroize, `num_complex` interop, `CachedCBig`, ball arithmetic,
+  rounding, `CBig` serde/rkyv/zeroize, `num_complex` interop, ball arithmetic,
   `CRound` independent re/im rounding, vector ops) — see §3.4 for the full consolidated list.
+  (`CachedCBig`, originally in this list, has been implemented — see the Phase 3 status note above.)
 - The full **C `<tgmath.h>` type-generic math surface** — the complete C standard math library for
   *both* real and complex (trig & inverse; hyperbolic & inverse; exp/log family including
   `exp2`/`exp10`/`expm1`/`log2`/`log10`/`log1p`; power/root `cbrt`/`hypot`/`pow`/`sqrt`; error & gamma

complex/CHANGELOG.md

@@ -3,6 +3,19 @@
 ## Unreleased
 
 ### Add
+- `CachedCBig` — a cache-backed variant of `CBig` mirroring [`dashu-float`'s `CachedFBig`]. It wraps a
+  `CBig` plus a shared `Rc<RefCell<ConstCache>>` handle, and threads that handle through the complex
+  transcendentals (`ln`, `exp`, `sin`/`cos`/`tan`/`sin_cos`, `asin`/`acos`/`atan`, `powf`, `arg`) so the
+  underlying real constants (π, ln2, ln10, …) are reused and progressively extended across a computation
+  chain instead of recomputed from scratch. It reuses `ConstCache` unchanged (there are no
+  complex-specific constants to cache), mirrors `CBig`'s full always-on trait surface
+  (`Display`/`Debug`/`FromStr`, `Ord`/`PartialOrd`/`AbsOrd`, `From`/`TryFrom` conversions, the binary
+  operators incl. cross-type ops against both `CBig` and `FBig`, `Neg`/`Inverse`, `Sum`/`Product`),
+  and is `!Send + !Sync` (so `CBig` itself stays `Send + Sync` and `static_cbig!` is unaffected).
+  Third-party traits (serde/num-traits/num-order/num-complex/rand) are intentionally not mirrored —
+  reach them via `.as_cbig()`. `CachedCBig::into_parts` returns `(CachedFBig, CachedFBig)` sharing the
+  handle (an intentional divergence from `CBig::into_parts`'s `(FBig, FBig)`). The meta-crate gains a
+  `dashu::FastComplex` alias (the complex twin of `FastReal`/`FastDecimal`).
 - `core::iter::Sum`/`Product` for `CBig` (and `Sum<&CBig>`/`Product<&CBig>`), folding with the
   binary `+`/`*` operators. The impls are concrete (`Sum`/`Sum<&CBig>`, `Product`/`Product<&CBig>`),
   matching the narrowed iter surface used for `FBig`; a correctly-rounded (exact-accumulating) `Sum`