Harden cached() callable typing for methods, generics, and overloads

[lan17]

Priority

P1 — High — resolve before broad production adoption or large-scale use.

Problem

CachedFn is rebuilt from Parameters<Fn> and ReturnType<Fn>. This loses a function's this parameter, generic input/output relationship, and overload set. Runtime invocation also calls a bare function without forwarding a receiver; the README tells method users to bind manually.

Evidence:

• Callable type reconstruction
• Runtime invocation
• Documented method caveat

Open decision

Research what TypeScript can preserve faithfully. Unsupported callable shapes should be rejected or precisely documented rather than appearing fully preserved.

Acceptance criteria

• Add compile-time tests for ordinary sync/async functions, explicit this, generics, and overloads.
• Preserve supported relationships in both ESM and CJS declarations.
• Make unsupported cases evident at compile time or precisely documented.
• Preserve the always-Promise return contract.
• Run declaration tests against the packed package, not only source types.