Solar Return solar@1 — Specification (W-05)

Status: Implemented v1 convention · Task: W-05 · Updated: 2026-10-25 · Implementation: W-08 package.

A return is the instant a body reaches a target ecliptic longitude again, followed by the chart for that instant. Two separate jobs live here: a bounded root search through Composer probes, and an event-chart request under an explicit location policy. The search must never present a sampled grid point as a solved event, and the event chart must never assume a location.

1. Admitted variant

Rule payload (validated by validateReturnRules):

{
  "body": "sun",
  "target": "reference-longitude",
  "solver": "bisection",
  "gridStepMilliseconds": 21600000,
  "toleranceMilliseconds": 1000,
  "toleranceDegrees": 0.0001,
  "maxEvents": 1,
  "maxProbesPerEvent": 64,
  "halfWindowDays": 3,
  "maxHalfWindowDays": 15
}

body is sun only in v1. A manifest admits one entry per technique, so a lunar or planetary return is a different bundle and variant, not a request parameter.

2. Inputs

3. Target longitude

L0 = reference snapshot Sun longitude, degrees in [0, 360)

L0 is read from the admitted reference snapshot; it is never recomputed from birth data, rounded by the technique, or overridden by the caller. If the reference has no Sun, the technique is INSUFFICIENT_INPUT. A caller-chosen target longitude is a different variant (§12).

4. Bounded search

4.1 Window

halfWindow = request.halfWindowDays ?? rules.halfWindowDays
start      = anchorInstant - halfWindow × 86 400 000
end        = anchorInstant + halfWindow × 86 400 000
span       = end - start

The window is inclusive at both ends. Validation, before any acquisition:

The window is never clipped to fit a budget. A smaller window is a caller decision.

4.2 Grid

step = request.gridStepMilliseconds ?? rules.gridStepMilliseconds

step must be ≥ ProbeBudget.minimumStepMilliseconds; a smaller value is LIMIT_EXCEEDED, never silently raised. Samples are start, start + step, … , end with the final sample at end even when the spacing is shorter. Samples are requested through ProbePort.series; no interpolation is performed or accepted.

4.3 Residual

r(t) = wrap180(λ_body(t) - L0),  range (-180, 180]

wrap180 is defined in the composite specification §3.1. The wrapped residual is what makes the search wrap-safe.

4.4 Bracketing

For consecutive samples a < b:

The |Δr| > 180 guard is the difference between a return and a representation artifact. A raw λ - L0 comparison would report a false event every time the body crosses 0° away from L0; that is the defect the third row prevents.

A crossing that occurs inside one grid step is found by the step size, not by assumption. The Sun moves at most ~1° per day, so a 6 h step cannot hide a solar return; a body with unknown speed or a retrograde station (the turning point where apparent motion reverses) may hide one, which is why the retrograde fixtures exist.

4.5 Refinement

Bisection on the bracketed sign change:

lo, hi = bracket
loop:
    best = endpoint with the smaller |r|
    if (hi - lo <= toleranceMilliseconds) and (|r(best)| <= toleranceDegrees):
        return solved(best)
    if probesUsed >= maxProbesPerEvent:
        return exhausted(lo, hi)
    mid = floor((lo + hi) / 2)
    probe(mid)
    replace the endpoint whose residual has the same sign as r(mid)

• Both tolerances must be satisfied: the time bracket is not sufficient on its own, and the angular residual is not sufficient on its own.
• The event instant is the endpoint with the smaller |r|; its residual and the bracket width are both retained.
• maxProbesPerEvent is bounded by the remaining ProbeBudget.maxEvaluations; whichever is smaller wins. Exhausting either is exhausted, never a snapped answer.

5. Candidate selection

• Events are sorted by instant; two events within toleranceMilliseconds of each other are the same event and are deduplicated (keep the one with the smaller residual).
• ambiguous is a value, not an error: a retrograde body can legitimately cross its target three times in one window. The result carries every solved event so the caller can choose.
• no-event is a successful result. It carries the searched window, the grid step, the probe count and the residual range, so “nothing happened” is auditable.
• exhausted carries the consumed evaluation count and the unresolved bracket; it is distinct from LIMIT_EXCEEDED, which is raised before acquisition when the declared limits cannot be met.

6. Location policy

locationPolicy is required and has no default:

• birth with no reference houseObserver is INVALID_REQUEST; no birth place is invented.
• current and event differ only in intent and in the label retained in the result. Both require an explicit WGS84 observer.
• Geocentric profile: the search is location-independent (the event instant does not depend on the observer); only the event chart uses the policy observer. Both the search origin and the event observer are recorded.
• Topocentric profile: the search is location-dependent (parallax changes the longitude). The policy observer is pinned before the search, used for every probe, and retained as searchObserver. The same request with a different location legitimately yields a different event instant; that is reported, not hidden.
• The policy is never inferred from the anchor instant, the reference chart’s civil timezone or a “likely” location.

7. Event chart

After an event is solved, the event chart is composed once:

toChartContextInput(profile, {
  instant: event.instant,
  houseObserver: policyObserver,
  positionObserver: profile.positionOrigin === 'topocentric' ? searchObserver : undefined
}, { houses: true })

The event chart is observed astronomy at the event instant, not a derived chart. It retains its own snapshot hash and Binder evidence. Nothing about it is labelled derived.

The event chart is not composed for no-event, ambiguous (until the caller picks an event) or exhausted outcomes.

8. Result

retrograde is true when the sampled speed at the solved instant is negative and null when the speed is unknown — it is never defaulted to false.

9. Composer facts and ports

Declared requirements: snapshot: 'none', composer: true, upstream: ['positions', 'probes'], optionalUpstream: ['houses'], dependencies: [].

Probe session ownership. WesternUpstreamBindings.probe is an already-open session, not a factory. The engine must open it with the technique’s declared window, step and evaluation limits (or hand the feature ComposerPort.openProbeSession), otherwise the technique cannot enforce §4.1 before its first read. See index P2.

10. Failures

11. Worked examples

Synthetic Sun model used by the fixtures: λ(t) = wrap360(NAIBOD × d), where d is days since 2020-01-01T00:00:00.000Z and NAIBOD = 0.9856473590852142 °/day. L0 = 100°.

R1 — solved event. Window 2020-04-11T00:00:00Z ± 3 days, step 6 h.

r(101.25 d) = 0.9856473590852142 × 101.25 - 100 = -0.203204892622°
r(101.50 d) = 0.9856473590852142 × 101.50 - 100 = +0.043206947149°

bracket 2020-04-11T06:00:00Z .. 2020-04-11T12:00:00Z
event   2020-04-11T10:56:52.560Z
residual 0.000000° (within 1e-4), bracket < 1000 ms, direct

R2 — wrap, not a return. Target 100°, body moves 350° → 10° at 1°/day over 20 days. wrap180 residual goes +110° → -90°: no sign change, { status: 'no-event' }. A raw λ - 100 difference goes 250 → -90 and would fabricate a crossing; the fixture asserts the wrapped result.

R3 — retrograde triple crossing. Piecewise synthetic body: +1°/day to day 10 (λ=10), -0.5°/day to day 30 (λ=0), +1°/day to day 40 (λ=10). Target 5°.

day 5   λ=5   direct
day 20  λ=5   retrograde
day 35  λ=5   direct

With maxEvents: 1 the outcome is ambiguous with three solved events; with maxEvents: 3 it is solved only if the technique variant admits three, which solar@1 does not. The fixture tests the solver directly, not the sun capability.

R4 — exact grid hit. A target that lands exactly on a sample returns that instant with residual 0 and zero refinement probes.

R5 — window edge. An event exactly at end is included; an event one millisecond after end is not. The half-open/closed choice is the §4.1 inclusive window.

R6 — budget rejected early. A 40-day window with a 1-minute step needs 57 601 samples; with maxEvaluations: 2048 the call is LIMIT_EXCEEDED before the first read.

R7 — location policy. { kind: 'event', observer: London } on a geocentric profile: the event instant is identical to the birth policy, but the event chart’s cusps are cast for London. On a topocentric profile the same change moves the instant; both instants are reported.

12. Unsupported variants

13. Prerequisites before W-08

The implementation and coordinator integration now satisfy these runtime seams; convention sources remain the responsibility of each supplied production rulebook. See the package tests.