[KIM] Return a state-isolated periodic local response

[krystophny]

Parent

#248

What to build

Expose one complete, state-isolated forced-periodicity KIM response for a single resonant mode. A caller must receive the local validity window, potential, physical electric and misalignment-field components, prescribed radial magnetic drive, and species-resolved parallel current without relying on global-solver array semantics.

The periodic solve may use process-global equilibrium machinery internally, but no plasma or grid state may remain changed after a successful or failed library call. This slice supplies the stable local-response boundary used by all later QL-Balance work.

Acceptance criteria

• The response identifies the resonance, local radial grid, as-is core, transition zone, period, and Fourier normalization.
• It returns the potential and its Fourier coefficients, physical electric-field components, the periodic misalignment field, prescribed radial magnetic field, and species-resolved parallel current.
• Radial electric fields are obtained with the periodic spectral convention and reproduce an analytic single Fourier mode to the declared tolerance.
• Public results cannot expose unallocated global-only arrays as if they were periodic output.
• Scaling the complex radial magnetic drive by a complex scalar scales potential, electric fields, and current linearly.
• Solving mode A, then mode B, then mode A again reproduces the first A result.
• Global plasma and grid state are restored after both successful solves and injected failures.
• Focused KIM library tests cover the result contract, scaling, state restoration, and failure cleanup.
• The delivered response satisfies the periodic misalignment-field requirement tracked by E_perp^(MA) is emitted only by the global FEM path, not by the periodic one #248.

Blocked by

None - can start immediately.