Custom comet elements

Create, repair, rename or remove local orbital-element records while KOPR keeps repositories, selectors and open workspaces transactionally consistent.

Current behaviour: custom-element edits are written atomically and reconciled across open selectors and workspaces. The interactive loader uses NASA/JPL SBDB; loading does not write anything until the user confirms the selected object and orbit solution.

When to use custom elements

Use CustomElements.dat when you need an explicit user-supplied orbital record or override for a valid canonical designation. It participates directly in the current Planner catalogue alongside Elements.txt.

CometData.dat is historical apparition support, not a substitute for adding a current Planner target. A missing-elements state is also distinct from invalid designation syntax: correct syntax first, then use the explicit editor action.

Add a comet or manage existing custom records

Action	Use it for
Database → Add comet…	Create a new custom-comet record. This action is add-only; it is not the editor for existing records.
Database → Custom comets…	Search, inspect, edit or delete existing custom records.

The Custom comets… manager provides a searchable list plus Save changes, Revert, Delete and Close. It can refill orbital fields from NASA/JPL SBDB, but an SBDB refill is only an editor update: it does not save the record until you explicitly choose Save changes.

Missing-elements prompts in observation/planning workflows remain explicit: validation reports the missing local orbit and lets the user start the add workflow, but does not silently modify the database.

Supported record operations

Operation	Expected result
New designation	Create the first custom record and publish the new catalogue identity.
New apparition	Add another apparition without replacing unrelated records for the same designation.
Replace matching apparition	Replace only the apparition that matches the editor transaction.
Exact selected-record update	Update the selected persistent record rather than relying on a designation-prefix match.
Rename	Publish both the old and new identities so open widgets can resolve the complete impact.
Delete with fallback	Remove the selected apparition and reconcile the remaining apparition as the available fallback.
Delete without fallback	Remove the final custom record and propagate the resulting missing-elements state.

Every operation is validated before persistent state or open-widget state is changed.

Atomic write and stable repository snapshot

The editor prepares a validated mutation against the exact persistent state it opened. An optimistic stale-writer check runs before the atomic replacement. After a successful write, KOPR publishes a new process-local repository generation.

On POSIX systems, cooperating writers use the established file-locking path. On Windows, KOPR uses a cooperating sidecar lock with msvcrt.locking and retries only transient sharing/access violations (WinError 5/32) for a bounded interval. A permanent replace failure leaves the original CustomElements.dat unchanged and does not publish a new process-local generation. Temporary-file cleanup must not hide the primary transaction error.

Repositories rebuild from a stable snapshot. One detected repository race triggers a retry. If the repository changes again during the retry, neither the primary cache nor derived catalogues are published from an unstable snapshot. Retry after other edits have completed.

Rename, deletion and open-widget impact

Rename publishes both old and new canonical identities. Deletion publishes whether another apparition remains available. KOPR resolves the impact globally across open consumers rather than refreshing only the editor that initiated the change.

Comet Analyzer reconciles the target catalogue and fully reloads an affected active typed target.
Observation Planner preserves use_all or the explicit subset against the repaired catalogue.
A removed final record becomes a true missing-elements state; a remaining apparition becomes the fallback.

Selector PREPARE → COMMIT → rollback

The shared selector prepares one reconciled state for both panes before it changes the visible selection. It commits only after all required updates succeed. Faults during commit trigger rollback to the previous selector state rather than leaving Selected and Not selected partially updated.

A successful nested-editor Save remains a durable file transaction even if the outer selector is later cancelled. The selector rollback affects the outer selection transaction, not the already committed element file.

WStack typed preview and failure states

WStack preview work carries typed element identity and repository generation. The UI distinguishes a genuine missing-elements result from an execution/runtime failure. A stale or failed preview cannot be reported as if the comet simply had no elements, and it cannot commit an obsolete result after the repository changes.

NASA/JPL SBDB loader and identity boundary

The interactive Custom Comet loader uses NASA/JPL SBDB rather than MPC get-orb. Exact designation and strict parent/fragment identity are required. Multiple object identities require explicit object selection and a new exact designation request; multiple orbit solutions require explicit orbit selection. J2000/schema gating and TDB→TT conversion are enforced. Loading remains no-write until explicit confirmation.

Backup and portability

The persistent user file is config-files/CustomElements.dat. Include it when backing up or moving the complete config-files/ directory. The fixed-width on-disk format is retained.

How custom elements participate in KOPR

Source	Current role
`Elements.txt`	Current MPC catalogue/current osculating elements.
`CustomElements.dat`	User-supplied base or override.
`CometData.dat`	Auxiliary apparition history for legitimate periodic/lost-periodic targets.

Planner current membership is Elements.txt + CustomElements.dat. For an already resolved apparition, source precedence is Custom > Elements > CometData. Custom-element updates use atomic writes and rollback-safe selector reconciliation.

Related chapters

Comet designation · Comet Analyzer · Observation Planner · CustomElements.dat · Troubleshooting