R211 Custom-elements integration baseline

Persistent transaction

1. Validate the canonical designation and element fields.
2. Format the record using the established fixed-width representation.
3. Read the current persistent state and verify the optimistic writer identity.
4. Refuse a stale writer before replacement.
5. Write and durably replace CustomElements.dat atomically.
6. Publish a new process-local repository generation only after the persistent commit succeeds.

R211 does not redefine the persistent data schema. Transactional safety and refresh ownership are the integration changes.

Repository generation and cache refresh

Repository generation is a process-local monotonic invalidation signal. Multiple already-open CometElementRepository instances compare their cached generation with the published generation and refresh automatically before returning catalogue data.

A consumer must not retain a repository snapshot as indefinitely authoritative. Persistent edits are observable without reopening the application.

Shared selector reconciliation

• Build one canonical supported catalogue after repository refresh.
• Reconcile Selected and Not selected from the same state transition; do not refresh the two panes independently.
• Automatically select a genuinely new canonical designation.
• Preserve side membership for metadata-only updates.
• Preserve Planner use_all over the refreshed supported catalogue.
• Do not force window activation or raise operations.

Widget boundaries

Comet Analyzer reload contract

Updating persistent elements for a currently active Analyzer target invalidates the typed target/dataset identity. The current target must be reloaded completely. This requirement survives cancellation of the outer selector because the nested editor's successful Save has already committed independently.

WStack stale-generation guard

Asynchronous WStack results carry the repository generation used during validation. A callback must compare it with the current generation and reject stale work. No stale preview or astrometry-group validation may overwrite a newer element state.

Qt ownership and modality

• The nested editor is parent-scoped Qt.WindowModal.
• The editor constructor does not call its own event loop.
• No validation callback opens the editor automatically.
• The common selector does not call raise_() or activateWindow().

These rules reduce focus and nested-loop hazards, but R211 does not claim native Wayland qualification without the required hardware/runtime pass.

R211 release gate

The cumulative Qt-free integration gate covers fixed-width record creation, atomic replacement, optimistic conflict refusal, generation publication, multi-instance cache refresh, Analyzer/Planner catalogue reconstruction, selector reconciliation, Planner use_all, Analyzer typed reload and stale WStack generation rejection.

The skips are real PyQt5/offscreen tests unavailable on the build host. These values are report evidence, not results rerun by the static documentation package.

Remaining native qualification

1. Analyzer selector → Add custom comet → Save and Cancel.
2. Planner selector with use_all and an explicit subset.
3. Visual, WCCD and WStack explicit missing-elements buttons.
4. WStack Calib asynchronous preview and astrometry-group action.
5. Persistent update of an already loaded Analyzer target.
6. No traceback or QSocketNotifier warnings.

Run both offscreen PyQt5 and native Linux/Wayland passes before describing the build as fully GUI-qualified.

Evidence

R211 release-gate report · Compact reference · User workflow

R217 successor authority

Use R217 Custom-elements repair flow architecture for the current cumulative contract. R211 rules remain required but are no longer sufficient for rename, deletion, repository races, selector rollback or MPC trust-boundary work.