[Feature] Missing JSDoc on public API — systematic pass

[pathosDev]

Size / Priority

• Size: M — many files; sustained effort.
• Category: C.2 Simplifications & DRY (documentation).
• Risk: low.

Affected files

• Every src/* file with public exports.

Background

JSDoc coverage on public APIs is uneven:

• Core types (Actor, Behaviors) have comprehensive JSDoc.
• Many feature additions ship without JSDoc.
• Some private methods have JSDoc; some public methods don't.

Effects:

• IDE hover/IntelliSense shows nothing for some public APIs.
• TypeDoc output (if generated for the documentation site, Documentation site (TypeDoc + custom layout) #26) has gaps.
• Onboarding is harder.

Target

Systematic pass: every public export gets:

• One-paragraph summary.
• @param for each parameter.
• @returns for non-void returns.
• @throws for documented error cases.
• @example for complex APIs (optional).
• @deprecated for legacy APIs.

// Before:
export function ask<R>(target: ActorRef, msg: unknown, timeoutMs?: number): Promise<R>;

// After:
/**
 * Send a message and await a single reply.
 *
 * @param target - The actor to send the message to.
 * @param msg - The message payload.  Must be JSON-safe if `target` is remote.
 * @param timeoutMs - Maximum time to wait for a reply.  Default: 5000ms.
 * @returns A Promise resolving to the reply.
 * @throws {AskTimeoutError} If no reply is received within `timeoutMs`.
 *
 * @example
 *   const reply = await ask<{ ok: boolean }>(serviceActor, new GetStatus(), 1000);
 */
export function ask<R>(target: ActorRef, msg: unknown, timeoutMs?: number): Promise<R>;

Implementation strategy

Per-PR:

1. Pick a module (e.g. src/cluster/*).
2. Identify all public exports.
3. Add/improve JSDoc.
4. Run a lint pass that requires JSDoc on every public export.

Multiple PRs over time. Tracked as a long-running cleanup goal.

Integration / risk

• No behavioural change.
• TypeDoc / documentation-site benefits.

Test plan

1. Documentation generation: run TypeDoc; visual review.
2. Lint pass: enforce JSDoc on all public exports.

Acceptance criteria

• Lint rule: public exports require JSDoc.
• Multi-PR pass to bring coverage to 100%.
• Per-PR module covered.
• TypeDoc output reviewed.
• CHANGELOG entry per major module covered.

Coordination

Coordinate with #26 (Documentation site with TypeDoc) — JSDoc is the prerequisite. This issue feeds that one.