# KOPR Live Theta-38 → Theta-60 — souhrn změn pro tvorbu dokumentace

**Datum:** 2026-08-25  
**Rozsah:** mainline KOPR Live Theta, verze Theta-38 až Theta-60  
**Cíl:** podklad pro aktualizaci uživatelského manuálu, technické/vědecké dokumentace, developer dokumentace a changelogu.

## 1. Pravidla interpretace

Tento souhrn popisuje mainline KOPR Live Theta. Izolované vývojové větve KOPR-Tail a KOPR-Spacecraft se do historie mainline Theta nezapočítávají, pokud nejsou výslovně integrovány do mainline.

Pro dokumentaci je nutné rozlišovat:

- **aktuální chování Theta-60** — to má být popsáno v uživatelském manuálu;
- **historické mezikroky** — patří do changelogu a developer historie;
- **superseded / opravované meziverze** — nesmějí být popisovány jako aktuální chování.

U release, pro něž nebyl v dostupném dokumentačním corpus nalezen samostatný autoritativní release report, je to níže výslovně uvedeno. Takovým verzím se nemají doplňovat konkrétní změny odhadem.

---

# 2. Chronologický přehled

## Theta-38 — Planner overview rendering correctness

- Opraveno clippingování čar overview mapy: constellation figures, D-footprinty, comet track a time arrows zůstávají uvnitř mapového pole.
- Opravena škála velikostí jasných hvězd v overview; sedm kroků 6.5 → 0.5 mag je opět skutečně monotónních a legenda používá stejný resolver jako vykreslené hvězdy.
- D1/D2/... labely detailních footprintů se přesunuly mimo vlastní footprinty a zůstávají uvnitř overview pole.
- Zavedena kompatibilní map-stack matice sheet v3 / renderer v6 / overview v4 / PDF v8.
- Nezměněny: N-body algoritmus, 0.25 mm track contract, TYC2/Yale membership, 6.5-mag overview limit ani monochrome/B−V provenance-only policy.

**Pro uživatelskou dokumentaci:** finding-chart overview lze popisovat jako stabilní bounded 30–60° overview s korektní magnitude legendou, clippingem a D-reference labely.

## Theta-39 — Custom Comets manager + N-body near-parabolic robustness

### Custom Comets

- Do `Database` přidán samostatný **Custom comets...** manager.
- **Add comet...** zůstává add-only a neslouží k editaci/deletování existujících custom záznamů.
- Manager podporuje searchable list, editaci, Save changes, Revert, Delete, Close a JPL SBDB refill bez implicitního uložení.
- Zachován existující `CustomElements.dat` formát, validace, atomic persistence a repository invalidation.

### N-body

- Opraveny numerické problémy Keplerova řešiče velmi blízko `e = 1` na hyperbolické i eliptické straně.
- Použity cancellation-safe residuals/derivatives; hyperbolická větev používá safeguarded monotonic Newton solve s bracketem.
- `PARABOLIC_ECCENTRICITY_TOLERANCE` se nezvětšoval.
- Planner zůstává fail-closed: skutečný N-body fail nesmí být publikován jako two-body výsledek.
- Cache policy zůstala zachována.

**Pro vědeckou dokumentaci:** změna je numerická robustnost osculating-state conversion, nikoli změna fyzikálního N-body modelu.

## Theta-40 — Planner per-comet ephemeris failure isolation

- Selhání jedné komety už nesmí shodit celou multi-comet Planner ephemeridu.
- Jakmile selže libovolný interval/apparition job konkrétní komety, daná kometa se publikuje atomicky jako neúspěšná — nikdy ne částečná ephemerida.
- Ostatní úspěšné komety se normálně vykreslí/publikují.
- Uživateli se zobrazí warning se seznamem přeskočených komet a jejich chyb.
- Pokud selžou všechny komety, zachovává se fail-closed chování a předchozí tabulka.
- Generate Maps bere cíle pouze z skutečně publikovaných ephemeris rows, takže failed comet není map-selectable.
- Bez změny N-body matematiky, scheduler policy, COBS photometry nebo visibility modelu.

## Theta-41 — Planner map dense-remainder fix

- Adaptive catalogue packing už neselže, pokud vznikne poslední/detailní remainder sheet obsahující pouze dense physical-track vertices (`annotation=False`).
- Takový sheet zdědí validovaný parent photometric star limit.
- Geometry placeholder magnitude `99.0` se nepoužívá jako photometric depth.
- Bez parent photometric contextu workflow stále failuje closed.

**Pro dokumentaci:** jde o robustnost Generate Maps, nikoli změnu katalogové hloubky nebo trajektorie.

## Theta-42 — Windows CustomElements atomic-write hardening

- Windows persistence `CustomElements.dat` dostala skutečný `msvcrt.locking` sidecar lock pro cooperating KOPR writers.
- `os.replace()` retryuje pouze WinError 5/32 v bounded časovém okně.
- Permanentní replace failure ponechá původní `CustomElements.dat` beze změny a nepublikuje novou process-local generation.
- Cleanup `.tmp` už nesmí maskovat primární transaction exception.
- POSIX `fcntl.flock` chování zůstává zachováno.
- Formát `CustomElements.dat`, SBDB import a orbitální věda se nemění.

**Pro troubleshooting:** na Windows se transient sharing violation / antivirus/indexer lock krátce retryuje; trvalá chyba má být bezpečná a původní soubor zůstane zachován.

## Theta-43 — dokumentační mezera

V dostupném corpus nebyl nalezen samostatný authoritative Theta-43 release report. Je potvrzeno pouze to, že Theta-43 je baseline `0.1.0.dev558` pro Theta-44.

**Pravidlo pro dokumentaci:** nepřisuzovat Theta-43 konkrétní změnu bez doplnění původního release artefaktu/changelogu.

## Theta-44 — Analyzer manual-range model extrapolation + perihelion visibility

- AUTO X range zůstává observation-owned.
- Explicitní USER/manual X range je nyní autorizací extrapolovat vybraný fitted model do požadovaného zobrazeného intervalu.
- Extrapolace je omezena fyzickým half-widthem vybrané apparition; nesmí přejít do sousedního návratu periodické komety.
- Single-law model může rozšířit oba vnější konce.
- Pre/post nebo adaptive multi-segment model zachovává všechny interní breakpointy; mění se jen outer begin/end.
- Exact manual X stále funguje jako compute/render filter.
- Fit coefficients, observation filtering, ephemeris a rovnice se nemění.
- Grid byl přesunut pod model/reference layers, takže perihelion reference v `T = 0` není překryta grid line.

## Theta-45 — Analyzer view auto-fit + multi-target defaults + external Plot key

- X a Y manual edit state jsou sledovány samostatně.
- Pokud uživatel změní X a Y nechá untouched, Y se dopočítá z observations + připravených model points uvnitř požadovaného X intervalu; model-only část může Y rozšířit.
- Explicitně editované Y zůstává autoritativní.
- Fresh multi-target selection defaultuje na `Log(r)` / `mag - 5*log(dist)`; scenario restore zůstává scenario-owned.
- Perihelion identity se přesunula z redundantního `Reference` legend blocku přímo k reference lines.
- `Comets` a `Reference` legend blocks byly odstraněny.
- `Data channels`, `Perihelion side` a `Formulae` byly přesunuty do pravého figure-level **Plot key** mimo axes.

## Theta-46 — transactional multi-target projection defaults

- Multi-target default axes se pouze staged; live controls se nemění před úspěšným loadem nové typed observation dataset.
- Default `Log(r)` / distance-corrected magnitude se commitne až po úspěšném dataset commit.
- Load failure, cancelled COBS recovery nebo no-local-data path nechává původní axes beze změny.
- Fresh single-target selection zachovává aktuální projection.
- Scenario restoration zůstává autoritativní.

## Theta-47 — Analyzer rendering hardening

- Pokud rendered target nemá žádnou Formulae entry, dostane identitu v podmíněném **Targets without formulae** blocku; legacy `Comets` se nevrací a targety se neduplikují.
- Perihelion labels se generují jen pro visible references, směřují inward a jsou clipped, aby nevstupovaly do Plot key.
- External Plot key už nepoužívá fixed `right=0.72`; šířka se počítá z figure pixel width, DPI, délky textu a počtu sloupců.
- Long Formulae labels se wrapují a započítávají do vertikálního layoutu.

## Theta-48 — dokumentační mezera

V dostupném corpus nebyl nalezen samostatný authoritative Theta-48 release report.

**Pravidlo:** exact per-release změny nedoplňovat odhadem. Při finalizaci historického changelogu je potřeba dohledat release report nebo `docs/CHANGELOG.md` z Theta-48.

## Theta-49 — dokumentační mezera

V dostupném corpus nebyl nalezen samostatný authoritative Theta-49 release report.

**Pravidlo:** exact per-release změny nedoplňovat odhadem.

## Theta-50 — Analyzer target-owned formula styles baseline

Dostupné artefakty potvrzují Theta-50 jako authoritative baseline s označením:

`KOPR_LIVE_THETA-50_ANALYZER-TARGET-OWNED-FORMULA-STYLES`

Tento stav je důležitý jako stabilní před-GUI-reorganization baseline, ze kterého byla později znovu zahájena čistá lokalizační/GUI série. Samostatný release report s dostatečně přesným rozpisem Theta-50 delta však v dostupném corpus nebyl nalezen.

**Pravidlo:** do current dokumentace lze převzít konečné chování z Theta-60; do release-by-release changelogu Theta-50 nedoplňovat detailní implementační tvrzení bez původního reportu.

## Theta-51 — superseded GUI mezikrok

Theta-51 byla nevyhovující meziverze Analyzer GUI a následný vývoj byl záměrně restartován z čistého Theta-50 baseline. Tato verze proto nemá definovat současné rozmístění ovládacích prvků.

**Pro current manuál:** nepoužívat screenshoty ani layout popis z Theta-51.

## Theta-52 — Analyzer localization L1

- První čistá lokalizační dávka po návratu na Theta-50 baseline.
- Přesunuty top-level Analyzer/sidebar user-facing labels do canonical `src/kopr/config/translations.py`.
- User-visible English a layout zůstaly beze změny.

## Theta-53 — Analyzer localization L2

- Do translation catalogu přesunuty `Bortle survival curve`, `Point style`, `Point size`, jejich možnosti a tooltipy.
- Bez změny layoutu a funkčního chování.

## Theta-54 — Analyzer localization L3

- Lokalizovány scenario/diagnostics a Settings/Exclude texty v dotčených funkcích.
- Bez změny jejich funkce nebo layoutu.
- Canonical import topology se rozšířila pouze o validní translation dependency.

## Theta-55 — Analyzer GUI frame batch G1A

- Přidány dva **bezejmenné** vizuální rámečky bez nadpisů:
  1. `Select comets…`, Save/Load scenario, Export diagnostics;
  2. `Editing target` + combo + `Style…`, Load COBS, Load MPC, Open local data.
- `Settings and selections` zůstalo mimo oba rámečky.
- Bortle/Point style/Point size/Exclude v této meziverzi ještě zůstávaly v původních místech.

## Theta-56 — final Analyzer GUI organization

- Zachovány dva bezejmenné rámečky z Theta-55.
- `Settings and selections` zůstává mimo ně.
- Samostatný Exclude tab byl odstraněn.
- Do existujících Settings byly soustředěny:
  - `Exclude uncertain observations`;
  - `Exclude negative observations`;
  - `Bortle survival curve`;
  - `Point style`;
  - `Point size`.
- Nepřidávají se další pojmenované sections/groupboxes.
- Point style změna rebuildí pouze Data channels + fit-groups editor z current draft state a zachovává draft visibility/fit groups/color/marker; Cancel nic necommitne.
- Bortle zůstává model-curve nastavení; Point style/size jsou display-only.

**Tohle je layout, který má používat current uživatelská dokumentace.**

## Theta-57 — Analyzer datetime perihelion annotation rendering fix

- Opraven runtime pád typu:
  `TypeError: Cannot cast array data from dtype('O') to dtype('float64')`.
- Pro Date projection se perihelion annotation při visibility conversion už nevrací jako původní Python datetime objekt, ale jako Matplotlib numeric float.
- Oprava se týká pouze renderovací reprezentace reference annotation.
- Bez změny observations, fitů, photometry, ephemeris nebo scientific modelů.

## Theta-58 — WCCD localization Batch A

- Behavior-neutral incremental localization funkce `CCD.onpickStar()`.
- User-facing texty dotčené interakce byly přesunuty do canonical translations.
- Measure Tail behavior se v této verzi ještě neměnil.

## Theta-59 — WCCD Measure Tail redesign

- Tail workflow má explicitní state machine:
  `INACTIVE → WAITING_ORIGIN → WAITING_ENDPOINT → COMPLETED`.
- Origin mode je explicitně `APERTURE_CENTER` nebo `MANUAL`.
- Tail workflow už nepoužívá `CometCentroid` ani legacy `Centroid`.
- **Use aperture center** zachytí jeden frozen exact snapshot aktuálního comet aperture center.
- **Choose manually** použije přesný right-click jako origin; endpoint je další přesný right-click.
- Výpočet PA/length nadále používá authoritative `CalcTailpa(origin, endpoint)`; algoritmus PA se nezměnil.
- Pokud není validní center, workflow automaticky přejde do manual mode bez zbytečného dialogu.
- `Measure Tail Again` nabídne volbu originu při každém novém měření; preference se nepersistuje.
- Esc restartuje/change selection mode.
- Cancel při startu nového measurementu zachová předchozí completed result.
- Pending Tail state se čistí před přepnutím mimo Comet image.
- Stale source/state mismatch failuje closed.
- Visual Tail workflow se touto změnou nemění.

**Pro uživatelský manuál WCCD:** starý postup s automatickým centroidováním kliknutého počátku ohonu je superseded a nesmí být nadále popisován.

## Theta-60 — Analyzer Formulae alignment + Marcus `d_90` correction

### Formulae Plot key

- Magnitudové parameter rows `H0..., n...` už nejsou child-indent doprava.
- Začátek textu parametrů je na stejné horizontální úrovni jako text názvu komety / formula identity.
- Parameter rows nedostávají vlastní marker ani line sample; mění se pouze odsazení.

### Marcus compound H-G phase function

- GUI suffix `deg` byl odstraněn z `d_90`.
- `d_90` je **bezrozměrný dust-to-gas light ratio normalizovaný při 90°**; číslo 90 v indexu označuje referenční úhel, nikoli jednotku parametru.
- Scientific `dust_phase.py` nebyl změněn; jde o opravu GUI prezentace/jednotky.
- Typické interpretace Marcusova parametru zůstávají například kolem 0.1 pro velmi gas-rich kometu, přibližně 1–3 pro běžnější broadband visual mix a vysoké hodnoty pro dust-dominated případ; dokumentace jej nesmí uvádět jako úhel.

---

# 3. Co má být aktualizováno v uživatelském manuálu pro Theta-60

## Planner

1. Multi-comet ephemeris může skončit **partial success**: failed comet je vynechána jako celek a uživatel dostane warning; úspěšné komety zůstávají publikované.
2. Generate Maps robustně zvládá dense physical-track remainder sheets.
3. Existing finding-chart overview pravidla z Theta-38 zůstávají: bounded field, clipped geometry, správná magnitude scale a D-labely.

## Database / Custom Comets

1. `Add comet...` = pouze nový custom comet.
2. `Custom comets...` = správa existujících custom records.
3. SBDB refill neznamená automatické uložení změny.
4. Windows save může krátce retryovat sharing violation; permanentní chyba zachovává původní file.

## Comet Analyzer

1. Rozlišit AUTO vs USER/manual range.
2. Manual X dovoluje bounded model extrapolation; manual Y zůstává autoritativní, pokud bylo explicitně editováno.
3. Fresh multi-comet view používá `Log(r)` / distance-corrected magnitude až po úspěšném load/commit datasetu.
4. Aktuální Plot key je mimo graph a obsahuje Data channels, Perihelion side a Formulae; `Comets`/`Reference` blocks jsou superseded.
5. Target bez formulae má podmíněný `Targets without formulae` fallback.
6. Perihelion labels se zobrazují přímo u visible reference lines a zůstávají uvnitř axes.
7. Aktuální sidebar/layout odpovídá Theta-56, nikoli Theta-51.
8. Bortle, Point style, Point size a oba Exclude checkboxy jsou v Settings.
9. Formulae parameter rows `H0/n` nejsou odsazené doprava.
10. Marcus `d_90` uvádět jako dimensionless ratio, nikdy jako `deg`.

## WCCD

1. Measure Tail vysvětlit jako výběr `origin → endpoint`.
2. Origin lze převzít z aperture center nebo zvolit ručně.
3. Aperture-center origin je frozen snapshot; po jeho zachycení se nesmí automaticky posouvat.
4. Manual origin i endpoint jsou přesně kliknuté body, ne centroidované body.
5. PA/length calculation itself zůstává `CalcTailpa`.

---

# 4. Co má být aktualizováno v technické / vědecké dokumentaci

1. **Near-parabolic N-body initialization:** cancellation-safe Kepler residual/derivative handling kolem `e = 1`, bez widening tolerance a bez two-body fallback publication.
2. **Planner partial-failure semantics:** atomic per-comet failure isolation; žádné partial rows uvnitř failed comet.
3. **CustomElements persistence:** Windows bounded replace retry + cooperating sidecar lock; data format unchanged.
4. **Analyzer range semantics:** AUTO observation-owned vs USER-authorized bounded extrapolation; internal segmented-fit breakpoints immutable.
5. **Analyzer Y-envelope semantics:** manual-X can derive Y from both observations and prepared model points; explicit manual Y wins.
6. **Reference rendering:** perihelion science/provenance unchanged; only visibility, labeling and datetime numeric rendering representation changed.
7. **WCCD Tail measurement:** scientific vector is frozen origin → exact endpoint; centroid algorithms are no longer part of Tail input acquisition.
8. **Marcus phase model:** `d_90` is dimensionless dust/gas light ratio at the 90° normalization point; do not document `deg` as unit.

---

# 5. Co má být aktualizováno v developer dokumentaci

1. Všechny nové/materiálně editované user-visible texty mají pokračovat přes incremental localization v `src/kopr/config/translations.py`; nejde o globální jednorázovou migraci untouched GUI.
2. Canonical implementation zůstává pod `src/kopr/`; hard-zero invariants: žádné root→root implementation imports, žádné canonical SCC, žádné architecture violations.
3. Analyzer UI state changes mají být transactional: staging oddělený od commitnutí live state.
4. Plot key layout je semantic/responsive policy, ne fixed pixel/figure constant.
5. WCCD Tail workflow má explicitní state machine a stale-state fail-closed semantics.
6. Windows file persistence musí zachovat primary transaction error a původní target file při permanentním replace failu.
7. Native GUI `PASS` se nesmí tvrdit na hostu bez PyQt5; v takovém prostředí zůstává status `HOLD`, i když headless/core qualification projde.

---

# 6. Superseded informace, které je potřeba z dokumentace odstranit

- `d_90` jako hodnota v `deg`.
- Starý WCCD Measure Tail postup, kde se origin automaticky centroiduje podle kliknutí.
- Analyzer samostatný `Exclude` tab po Theta-56.
- Analyzer `Comets` a `Reference` legend blocks.
- Fixed-width external Plot key z Theta-45.
- Nevyhovující Theta-51 GUI groupbox/section layout.
- Tvrzení, že manual X range nemůže extrapolovat fitted model za observation support.
- Tvrzení, že chyba jedné komety musí shodit celou Planner multi-comet ephemeridu.
- Dokumentace Custom Comets, která zaměňuje `Add comet...` a manager existujících záznamů.

---

# 7. Dokumentační mezery k doplnění z historických artefaktů

Pro přesný release-by-release changelog chybí v aktuálně dohledaném corpus samostatné autoritativní release reporty pro:

- **Theta-43**;
- **Theta-48**;
- **Theta-49**;
- detailní delta **Theta-50** (release identity/baseline je doložena, ale ne kompletní samostatný report).

Tyto mezery nebrání popisu **aktuálního Theta-60 chování**, ale brání spolehlivému připsání konkrétní historické změny přesně danému release. Do historického changelogu je proto vhodné tyto položky doplnit až po nalezení odpovídajícího release reportu nebo snapshotu `docs/CHANGELOG.md`.

---

# 8. Doporučená struktura aktualizace hlavní dokumentace

1. **User Guide / Analyzer** — rozsahy, multi-target projection, Plot key, current Settings layout, Marcus phase settings.
2. **User Guide / WCCD** — nový Measure Tail workflow.
3. **User Guide / Planner** — per-comet failure isolation + current Generate Maps robustness.
4. **User Guide / Custom Comets** — Add vs Manager + Windows-safe persistence behavior.
5. **Scientific reference** — N-body near-parabolic robustness, Analyzer extrapolation policy, Marcus `d_90` semantics, WCCD tail vector definition.
6. **Developer architecture** — transactional GUI state, responsive Plot key, incremental i18n, persistence locking/state machines.
7. **Changelog** — jednotlivé Theta release; Theta-43/48/49/50 doplnit až z authoritative source.