Internal module guide. This module is now part of
@astrology/western; use the public package README for application setup.
returns module
Implements returns@1/solar, the solar return: search for the reference Sun longitude, then cast a chart at a unique solved instant under an explicit location policy. Lunar, planetary, precessed and caller-overridden targets are unsupported.
validateReturnRules admits the bisection convention and explicit grid/tolerance/window/refinement limits from the specification. ReturnRequest supplies the reference, anchor instant, location policy and complete C-04 budget; half-window and grid spacing may only fit the admitted bounds. prepareReturnSearch validates the entire grid and resolves the search context before any acquisition.
findReturnEvents(request, probe, rules) uses real bounded position reads, wrapped residuals and bisection. A raw 0°/360° discontinuity never counts as a return. Events must pass both time-bracket and angular-residual tolerances. Exact evaluated endpoints are included; close duplicates retain the smaller residual. No sample is snapped into a solved event. A short final grid remainder is acquired singly because C-04 series enforce their minimum spacing.
Search statuses are solved, no-event, ambiguous and exhausted. Results retain solved events, unresolved bounds on refinement exhaustion, residual range, consumed evaluations, probe evidence and solver limits. coverage: 'sampled-brackets' makes the resolution explicit: arbitrary hidden reversals or tangencies between samples are not excluded. Provider errors and cancellation propagate unchanged.
Location must be birth, current or event; current/event policies require an observer, and birth needs the reference house observer. Geocentric searches (positions measured from Earth’s centre) are location-independent. Topocentric searches (positions measured from the observer’s place) pin the selected observer before their first probe; recasting the solved event under a different search observer is rejected.
calculateReturnChart(event, locationPolicy, composer) acquires one observed event chart with houses and verifies its Sun still meets the solved angular tolerance. Changed provider astronomy cannot silently become a return chart. A positions-only reference needs an explicit eventHouseSystem and eventFrame in direct searches. The feature uses the profile house system/frame. No event chart is composed for no-event, ambiguous or exhausted searches.
createReturnFeature(admitted) declares Composer access and required positions/probes. Use engine.operation({ profile, technique: 'returns', request }); the coordinator opens the preflighted C-04 session. Envelope provenance retains reference/event charts and probe identities; exhausted searches are explicitly incomplete. No derived points are attached to observed return charts.