WStack current performance and Relative-WCS architecture

Immutable operation and metadata lifetime

• Stack preflight captures one immutable operation snapshot reused for parameter display, worker preparation and output naming.
• Detached FITS/WCS/time data cross worker boundaries as frozen serializable/card-image representations; mutable Astropy Header/WCS/Time objects are not shared as cross-thread session state.
• File identity is bound to path + size + mtime_ns. A mismatch forces authoritative disk reconstruction instead of trusting stale metadata.
• Calibration→Astrometry and Astrometry→Stack handoffs occur only after the producing stage has atomically installed and validated its product.

Stage-delta refresh and prepared-master workset

When KOPR owns a known filesystem change, operation completion can refresh the exact stage delta instead of rescanning the complete session. Reopen, manual refresh and externally mutated data keep the full-rescan fallback. Prepared master reuse is governed by a byte-budgeted working set rather than a fixed small number of dark/flat pairs; calibration math is unchanged.

Host-aware resource planning

• Mean/Sum reprojection: adaptive scheduler bounded by physical cores, useful blocks, RAM-safe planning and hard cap 8.
• Sigma-clipped mean: fused science+saturation reprojection with the same one-pass median/MAD scientific clipping contract, plus RAM and temporary-disk safety.
• Astrometry: workload/host-aware scheduler with hard cap 6 on the qualified native path, 50% available-RAM budget and 256 MiB reservation per solver. Unknown/WSL backends remain conservative.
• LIGHT calibration intentionally retains production cap 2; higher concurrency was measured but not adopted because the gain did not justify resource cost.

Scheduler decisions are workload-specific. “Use all cores” is not a KOPR policy.

Relative-WCS hybrid safety contract

Canonical Qt-free owner: kopr.core.stacking.relative_wcs. The application layer orchestrates routing, commit and fallback.

Any candidate exception, missing/bad AXY data or rejection reroutes the whole acquisition group to the original full-image validator. That validator remains the fallback safety authority. AXY payload is operation-local and must not persist to pipeline_state.json, manifests or FITS products.

Measured reference evidence

Source-reported measurements, not portable guarantees:

• Fused Sigma N=7 reference: approximately 2.87× faster than the historical two-transform/two-worker core at exact output/statistics parity.
• Theta-70→73 reference flow: 456.473 → 431.146 s (−5.55%).
• Relative-WCS broad corpus: 5 real comet sessions, 229 calibrated FITS, 10 groups, 0 fast-path false accepts, 0 hybrid/fallback decision divergences; measured section 408.332 → 69.976 s (−82.86%).

These benchmark percentages cover different, partly overlapping pipeline regions and must not be combined arithmetically.

Qualification boundaries and deferred work

• WStack native GUI status on the Theta-85 build host remains environment HOLD because the required PyQt5 runtime was unavailable; no native WStack PASS is claimed from that host.
• Planner native GUI PASS is separate component evidence and cannot substitute for WStack native qualification.
• The 8M Master/RAW optimization track remains deferred until representative DARK/FLAT source data exist. Phase 8 did not implement it.
• Performance changes require science parity evidence or separate scientific qualification; harness/supervisor faults must not be rewritten as product/science failures.

Related documentation

WStack user guide · Performance limits · Testing and qualification · Theta-60 → Theta-85 history