API audit findings for #4524: proposed first stabilization slice (discussion)

[Flamki]

Following up on #4524 and maintainer feedback in closed PR #4770, posting findings here for discussion before any code PR.

Context

• PR api: add initial #4524 audit slice and accessor hardening #4770 was closed with guidance to discuss findings first.
• Goal is pre-1.0 API stability planning (not immediate implementation).

What I audited

• Public API surface snapshot across publishable crates (cargo-public-api).
• First focused slice on boa_engine public-field exposure.

Key findings (first slice)

1. High-priority candidates for stabilization

• JsNativeError.kind and JsErasedNativeError.kind: direction was accessor-based API (kind()) instead of direct field access.
• OptimizerStatistics counters: direction was accessor-based API for forward-compatible evolution.

2. Medium-priority candidates for policy decision

• ResolvingFunctions { resolve, reject }: keep ergonomic shape vs. mark type #[non_exhaustive].
• RecursionLimiter { visited, live }: keep public internals vs. expose read methods only.
• JsPartialTime public fields: keep as data struct vs. reduce visibility/encapsulate.

3. Enum shape exposure to discuss

• TryNativeError and other enums with public variant fields may benefit from a project-wide rule on #[non_exhaustive] usage before 1.0.

Questions for maintainers

1. Do we want to adopt “prefer accessors over public fields” as a 1.0 policy baseline?
2. Should we standardize where #[non_exhaustive] is expected (which public enums/structs)?
3. Which crate/surface should be the very first implementation PR once policy is agreed (boa_engine errors, optimizer stats, or another area)?

If helpful, I can post a compact crate-by-crate matrix (public fields / non_exhaustive usage / suggested action) in this thread to drive decision-making.