Modal ephemeris architecture

R121 makes the approved per-widget ephemeris modes an explicit production contract rather than an implementation convention.

R515 structural note: This page preserves feature/release contracts, but any flat-root Python filenames cited as implementation evidence are historical pre-convergence names. Current implementation ownership is canonical under src/kopr/; use the current package/API policy for imports and extension work.

Authoritative widget policy matrix

R121 established modal per-widget scientific routes. R255 supersedes only the Planner-specific execution staging.

Widget	Current dynamics	Output/use
WVisual	DE440s N-body	Astrometric position
WCCD	DE440s N-body	Astrometric position
WStack	DE440s N-body	Astrometric position
WPlanner	Legacy 2-body search/filter → final cached DE440s N-body refinement of accepted rows	Final planner rows and frozen ICRS/J2000 map positions
Comet Analyzer / WLightCurves	Two-body photometric geometry	r, Δ, phase and analytical curves

Output profiles

Astrometric position

WVisual, WCCD and WStack retain DE440s Cowell-DOP853 N-body propagation and their established astrometric output path.

Planner two-stage full result

Planner uses two-body geometry for schedule/search/membership decisions, then refines only accepted frozen epochs through the persistent cached N-body engine. Generate maps uses those final frozen ICRS/J2000 positions and performs no new ephemeris calculation.

Photometric geometry

Comet Analyzer uses the approved two-body photometric geometry kernel for r, delta and phase and does not require the N-body astrometric worker for analytical curves.

Scheduling and cache boundaries

WVisual, WCCD and WStack use serial series scheduling and memory trajectory reuse.
WStack must create no process jobs and must not own persistent N-body segments.
WLightCurves uses the global point-batch route, one canonical memory-geometry identity and deterministic ordering; process scheduling is allowed only above the approved missing-point threshold.
A process worker must never start another process scheduler.
Qt and Matplotlib objects are forbidden from process payload modules.
Stale-result rejection, shared Cancel and transactional cache commit remain release-blocking contracts.

Deterministic R121 fixture	Contract
Ordinary analytical workload	10,000 points; local batch
Process threshold	200,000 missing points
Point-batch bounds	256–2,048 points
One 10,000-point apparition	At least 16 internal batches
12 × 20-point small apparitions	One coalesced batch
Cosmetic redraw	Zero new physical calls
Planner forward interval	500 points
Planner cold/warm integration count	1 / 0
Planner worker maximum	4 while reserving one CPU
WStack process jobs	0

Planner persistent validated segments

Persistent validated N-body segments remain an acceleration layer for Phase B, the final refinement of accepted rows. They are not used to scan twilight/best-time search space or rejected candidates.

R130 cache validation, schema, atomic writing and bounded worker rules remain active. R255 adds the accounting invariant that N-body requested epochs equal the final accepted legacy-row count.

Preserved scientific invariants

R121 changes no N-body force, DOP853 tolerance, two-body conic equation, light-time equation, element/apparition selection, adaptive curve sampler, H0/n law, phase correction, Planner best-time rule or displayed field. The modal architecture prevents a valid specialized kernel from being replaced by a heavier or scientifically inappropriate route.

See N-body internal ephemeris, Analysis performance and the R121 release gate.