R217 Custom-elements repair flow architecture

End-to-end flow

editor mutation
  → atomic optimistic write
  → repository generation and stable snapshot
  → catalogue reconciliation
  → open-widget impact resolution
  → selector PREPARE → COMMIT → rollback
  → WStack typed preview
  → JPL SBDB/identity trust boundary

No consumer may skip directly from file mutation to local UI patching. Each stage owns a specific consistency boundary.

Apparition-aware mutation model

• Create a new designation.
• Create a new apparition for an existing designation.
• Replace only a matching apparition.
• Update the exact selected record.
• Rename while publishing both old and new identities.
• Delete while publishing whether another apparition remains as fallback.

Persistent matching must be exact. Prefix collisions and designation-only replacement are not valid mutation identities.

Stable repository snapshots and race handling

1. Reject a stale writer before atomic replacement.
2. Publish process-local generation only after durable commit.
3. Read a repository snapshot and confirm that its generation remains stable.
4. On one race, discard the partial read and retry.
5. On a second race, publish neither primary repository cache nor derived catalogue/cache state.

This prevents a mixed-generation catalogue from becoming visible to open widgets.

Catalogue reconciliation and open-widget impact

Impact resolution consumes the complete set of affected identities, including both sides of a rename and the fallback state after deletion.

Selector PREPARE → COMMIT → rollback

Selector reconciliation first prepares a complete state for both panes and all dependent metadata. Only a successful preparation may enter COMMIT. Fault injection during commit must restore the previous selector state. The nested editor's already successful persistent mutation is not rolled back by cancelling or rolling back the outer selector.

WStack typed preview boundary

WStack must distinguish true missing elements from runtime failure. Preview results carry typed identity and repository generation. Stale generations, exceptions and cancellation cannot be converted into a false missing-elements result or committed after a newer mutation.

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.

R217 release gate

Run r217_custom_elements_repair_final_integration_release_gate.py and the current cumulative validators. The real PyQt5/offscreen integration smoke must be skipped, not simulated, when Qt is unavailable.

Native qualification HOLD

Promotion requires real offscreen PyQt5 and native Linux/Wayland execution covering modal nesting, global propagation, active-target updates during background work, WStack preview → editor → Save, shutdown with active work, selector fault/retry, verified MPC success/failure atomicity and absence of traceback, QSocketNotifier, QObject affinity, QThread destroyed while running and Wayland activation warnings.

The same codebase may be promoted from PASS_HEADLESS to PASS_OFFSCREEN_QT and then PASS_NATIVE_WAYLAND; no new production feature is required.

Evidence

R217 release-gate report · Compact repair-flow reference · User workflow · R211 baseline

R255 source-role overlay

R217 remains authoritative for mutation, stable repository snapshots, impact resolution and selector rollback. R255 assigns the repository sources explicit scientific/catalogue roles: current Planner membership is Elements + Custom, while CometData is auxiliary apparition history. Same-apparition precedence is Custom > Elements > CometData.