WPlanner source roles, two-stage dynamics and Generate maps

Qualified comet-element source roles

CometData.dat is not a generic current-catalogue layer.

Epoch-aware apparition and source resolver

The resolver first determines the physically relevant apparition. Within that same apparition the approved source precedence is:

Custom > Elements > CometData

This preserves historical periodic-target calculations while preventing auxiliary historical data from silently expanding the present-day catalogue.

WPlanner current membership

current Planner targets = Elements.txt + CustomElements.dat

A CometData-only designation cannot enlarge the current Planner selector. R217 custom-element mutation/reconciliation still applies to the user layer; R255 defines how that layer participates in current membership and epoch-aware selection.

R251/R255 two-stage Planner dynamics

Phase A — legacy 2-body search

Current candidates go through cheap filters/delta-T, schedule construction, best-time search, magnitude/phase correction, altitude and all row-membership filters. Accepted rows freeze the exact UTC epochs and selected element identities.

Phase B — final cached N-body

Only frozen accepted rows request persistent cached N-body refinement. The refined values become the final displayed values and final frozen ICRS/J2000 map positions.

N-body search epochs    = 0
N-body rejected epochs  = 0
N-body requested epochs = final accepted legacy-row count

No magnitude or altitude membership filter is re-applied after N-body refinement, and silent final fallback to a non-N-body model is rejected.

Night-diagram model boundary

The current night diagram deliberately uses the canonical legacy Stage-A two-body kernel for its low-resolution midnight/best-time/5-minute planning curves. Its UTC-aware night window is owned by kopr.core.planner.night_window and spans evening to the following morning, including fractional GMT offsets. Generate ephemeris and finding-map physical-track work remain on their qualified N-body paths. This is a scope distinction, not a numerical-equivalence claim.

Rendering preserves invalid/horizon gaps as NaN segments, bounds hour ticks and isolates per-comet failures; all-failed blocks an empty diagram.

Documented single-target map architecture

fresh final Planner rows
→ select exactly one map-eligible comet
→ freeze immutable document
→ deferred authoritative N-body physical-track refinement
→ overview/index + landscape detail sheets
→ Preview
→ atomic PDF export

Existing final Planner rows are reused, but Generate maps may compute missing dense epochs. The current physical-track contract probes every drawable segment at quarter, half and three-quarter times and refines until measured projected error is ≤0.25 mm or the bounded operation fails closed.

Per-comet ephemeris failure isolation

Planner publication is atomic per comet. If any interval/apparition job for one comet fails, no rows for that comet are published, while successful comets from the same multi-target operation remain available. All-target failure remains fail-closed and preserves the previous table. Map eligibility is derived only from actually published final rows.

Dense map remainder sheets

Adaptive catalogue packing accepts a remainder sheet that contains only unannotated dense physical-track vertices. It inherits the validated parent photometric star limit; geometry placeholder magnitude values are never treated as photometric depth. Without a valid parent photometric context, the workflow still fails closed.

Current catalogue, partition and rendering policy

• Fixed local roots: ./koprtyc2 and ./koprybsc5.
• Detail fusion priority: Yale > TYC2 > GSC1.1.
• Overview: independent TYC2+Yale acquisition to 8.0 mag, with server-side VizieR VTmag filtering and no GSC completeness dependency.
• B−V is provenance only; output is monochrome.
• Overview square TAN starts at 30° and expands by 1° to a hard 60° maximum.
• Detail-sheet partition minimizes sheet count and then uses balanced temporal/annotation load; the same principle is used by adaptive catalogue packing.
• Full-mode date labels use a coherent track-normal side where possible. Dense/short projected tracks may switch to endpoint-only text while preserving the complete physical track and markers; displaced labels use leader lines.
• Overview lines are clipped to frame; D labels are outside footprints.
• Mixed-version component preflight fails before expensive N-body/catalogue work.

R247 WCCD repair authority

R247 simultaneously qualifies the current WCCD repair boundary:

• validate complete requested background geometry before sampling; a one-pixel overflow is a typed hard failure;
• zero or negative ring medians do not disable valid upper-only ACF clipping;
• raw and filtered annular flux remain signed;
• degenerate sigma and invalid angular coverage have explicit typed states;
• None means unhydrated reference state, while [] is an authoritative empty state;
• Clear all stars atomically clears canonical/legacy/diagnostic/image-slot/measured-artist reference state while preserving the comet, catalogue overlays and frozen ACF context.

Current Planner qualification boundary

The supplied Theta-83 evidence closes the D1→D3C/MAP-R3 repair sequence without a newly demonstrated Planner defect. Planner native GUI behavior was separately exercised successfully on an xcb/PyQt host for the D3C scenarios. This component-specific PASS must not be generalized to unrelated GUI components.

Product QA figures on this developer page are inherited from source reports and are not rerun by the documentation package.

Supersession and retained historical contracts

• R130 remains the background-operation, interval/persistence performance foundation for the final N-body refinement phase, but not the authority for which Planner rows receive N-body work.
• R121 modal-ephemeris documentation is historical where it says N-body participates in Planner visibility/best-time search; R255 supersedes that Planner-specific statement.
• R217 remains the custom-element mutation/repository/selector-repair authority; R255 defines source roles and current membership.
• R239 remains the exact-designation MPC/Generate maps integration baseline; R247 hardens it; R255 defines the final workflow and source/dynamics semantics.

R239 report · R247 report · R255 report