WCCD aperture check and reference provenance

Scientific scope

APCHK is an observer advisory, not an automatic physical-coma-radius estimator. Its positive claim is intentionally narrow: when qualified ACF evidence supports it, the current manual aperture is too small and a larger radius is worth review. A non-actionable or non-extrapolatable result must not be rewritten as “the aperture is adequate” or “the coma ends here”.

The current contamination-resistant automatic adequacy path is authoritative for ACF measurements. Ordinary comet photometry remains supported but does not use the superseded raw-aperture comparator as an authoritative recommendation engine.

Frozen measurement transaction

Manual Comet Measure separates compute, candidate, commit and presentation. The successful ACF candidate freezes the image/source identity, centre, exposure time, ACF defaults, saturation/validity contract and ACFMeasurementContext.original_analysis. Review must consume this snapshot rather than re-reading mutable Settings or GUI state after the authoritative measurement.

Stale source/run/observation identity must fail closed instead of committing into another observation.

Same-measurement alternative-aperture principle

Each trial radius is evaluated as the observer's same measurement at a different aperture: same Comet image, same centre, same ACF parameters, same EXPTIME and validity/saturation rules, but the canonical WCCD local background appropriate to that trial radius. The old one-sky-for-all-radii model is superseded.

ACF Curve-of-Growth evidence

The review consumes cumulative ACF profile evidence including filtered cumulative flux, raw and used incremental flux, ACF clipping/intervention, local log-slope, robust local trend/prediction residual and additional photometric gain in magnitudes.

Raw/used divergence is contamination evidence. A strong raw stellar-trail increment that ACF removes does not automatically count as new comet flux; conversely, filtering intervention does not by itself prove the filtered CoG is unusable.

Sequential stop, observer-prefix scan and tiny-aperture bootstrap

Outer trials are evaluated sequentially. As soon as a trustworthy photometric-tolerance, contamination/evidence, CoG-reliability, frame-limit or hard-invalid boundary is reached, the sweep stops and no more distant aperture is measured.

Before the outer sweep, the frozen observer CoG is scanned from the inside outward so contamination already inside a large selected aperture cannot be normalized into the baseline. For tiny starting apertures, insufficient_cog_reference is treated as bootstrap state until enough points exist or a genuine hard failure occurs.

Selected preview versus measured state

Try suggested aperture creates a selected-but-unmeasured preview state. It updates/draws the proposed radius and stops. It must not run a new ACF measurement, replace the existing candidate or commit new photometry. The next authoritative result exists only after the observer manually invokes Perform Comet Measure. Repeating Comet Measure on the already active Comet image preserves the current viewport.

Reference-star source and background provenance

Canonical reference records carry source_id and source_role. The scientific ensemble is observation-global while measurement artists are source-local. Annotation restore is presentation-only.

New Auto Star Measure records retain frozen background validity, completeness, exact geometry and expected/actual sample counts. Late fallback recomputation is a legacy path and is permitted only against the exactly identified source image.

Background preflight decides individual eligibility, not whole-observation sufficiency. user_enabled=False and already quality_eligible=False records are skipped. A newly invalid reference becomes ineligible and processing continues; the canonical ensemble solver later enforces the minimum of three eligible stars and pairwise consistency. Comet background remains independently strict fail-closed.

Canonical ownership

src/kopr/core/photometry/comet_aperture_check.py
src/kopr/application/wccd_runtime.py
src/kopr/features/wccd/aperture_review_presentation.py
src/kopr/features/wccd/observation_contracts.py
src/kopr/config/translations.py

All active implementation remains under src/kopr/. New/materially edited user-visible text follows incremental localization through canonical translation keys; flat-root compatibility surfaces remain non-owning.

Current qualification boundary

Post-Theta-110 combined headless qualification reports 13/13 explicit combined-workflow PASS and 89/89 broader directly affected WCCD PASS, with 322 canonical Python files, 802 canonical import edges, 0 SCC and 0 architecture violations. No product-code change was made during that RQ, so no Theta-111 was created.

Native GUI smoke on the qualification host remains HOLD because PyQt5 was unavailable. Do not relabel headless qualification as native GUI PASS.

Real-FITS qualification covered 10P, C/2023 R1, 169P and C/2025 M2. The corpus supports the current V1 calibration and demonstrates both actionable larger-aperture recommendations and conservative non-extrapolatable outcomes.

Related documentation

User aperture-check workflow · ACF science explanation · Testing · Theta-86 → Theta-110 history