Internal module guide. This module is now part of @astrology/chart-composer; use the public package README for application setup.

probes module

createProbeSession(reader, canonicalContext, limits) supplies exact-instant reads and bounded series acquisition. readPositionSeries(session, { instants }) returns an ordered grid of actual reader results; there is no interpolation, astronomy implementation or root solver.

See the reading guide for the session’s state and reading order.

Budget admission

Limits include inclusive start/end instants, maximum window length, bodies and evaluation attempts, minimum series step and maxConcurrency: 1. All integer limits must be positive and the window must have nonzero length. Entire series admission happens before its first read, including remaining attempts, ordered instants and minimum step. Adaptive single probes may be closer than the grid step so engines can refine boundaries within the same evaluation budget.

Reuse and failure accounting

Successful contexts are reused only inside the session, with their original evidence. Attempts count even on upstream failure; failed instants are never retried. Concurrent callers are queued serially. Results carry cumulative consumed evaluations and a stable identity covering context, versions and evidence.

Cancellation and deadlines

Supply signal or a host-created deadlineSignal (for example AbortSignal.timeout(...)) in limits; individual evaluations/series also accept cancellation. Cancellation stops subsequent scheduling but cannot interrupt already executing native work because Binder has no abort method. No hidden clock influences a calculation identity. Upstream errors propagate unchanged. Local failures expose LIMIT_EXCEEDED, OUT_OF_WINDOW, or CANCELLED.

Event gate

A session installs riseSet only when its reader has the method; each call also checks its event capability. Only the Hindu rising definition is supported: disc centre, no refraction, geocentric Sun and ignored solar ecliptic latitude, following the Swiss native definition.

The location is context.houseObserver. Supply end, or the session uses the earlier of its own end and 72 hours after the request start. includeSunset: true requests the first sunset after sunrise. Nulls preserve native no-event results; no 24-hour day is manufactured.

Events share the serial queue and budget: reserve two evaluations for sunrise/next sunrise, or three with sunset. This is conservative even when polar cases require fewer calls. Cancellation/deadlines are checked after capability admission, before scheduling native work; already executing Binder calls cannot be interrupted.

Verification

Run the root build:chart-composer, check:chart-composer, and test:chart-composer commands. Tests use a controlled reader and cover admission, concurrency, cancellation, reuse and failures.