Custom comet elements

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.

Where the action appears

The nested editor is parent-scoped Qt.WindowModal. It does not start a second application event loop and it does not force raise_() or activateWindow().

Supported record operations

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

Atomic write and stable repository snapshot

1. The editor prepares a validated mutation against the exact persistent state it opened.
2. An optimistic stale-writer check runs before the atomic replacement.
3. After a successful write, KOPR publishes a new process-local repository generation.
4. Repositories rebuild from a stable snapshot. One detected repository race triggers a retry.
5. If the repository changes again during the retry, neither the primary cache nor derived catalogues are published from an unstable snapshot.

A conflict or double-race leaves the previously committed repository/catalogue state authoritative. 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 remains config-files/CustomElements.dat. Include it when backing up or moving the complete config-files/ directory. R217 changes repair, snapshot and integration behavior, not the fixed-width on-disk format.

Qualification status

R217 is PASS_HEADLESS and not fully qualified. The build remains on native-qualification HOLD because PyQt5/offscreen and native Linux/Wayland execution were unavailable.

The skipped tests require a real Qt runtime. Promotion requires both a real PyQt5 offscreen pass and a native Linux/Wayland pass.

How custom elements participate after R255

Planner current membership is only Elements.txt + CustomElements.dat. For an already resolved apparition, source precedence is Custom > Elements > CometData. The R217 atomic mutation, stable-snapshot and rollback rules remain unchanged.

Related chapters

Comet designation · Comet Analyzer · Observation Planner · CustomElements.dat · Troubleshooting · R211 integration baseline · R217 flow architecture