POTACAT: support full-fidelity multi-reference activation handoff

[rtreit]

Parent: #529

Related: #384

Summary

Define and implement a full-fidelity POTACAT-to-QsoRipper handoff for multi-park, park-to-park, SOTA, and cross-program activations without creating duplicate QsoRipper QSOs.

This is a follow-up to baseline Extra UDP integration. It requires an upstream POTACAT change because current POTACAT forwarding sends only the first record from its local ADIF cross-product.

Current limitation

POTACAT currently creates separate ADIF records for combinations of local and worked references. Secondary records receive separate UUIDs and are marked skipLogbookForward, so QsoRipper receives only the first combination through Extra UDP.

Forwarding every existing cross-product record is not the solution because it would represent one physical contact as multiple QsoRipper QSOs.

Interchange contract

Prefer one canonical handoff record per physical contact containing:

• One stable external physical-QSO identity.
• An optional stable external activation-session identity.
• Complete local POTA reference list.
• Complete worked POTA reference list.
• Local and worked SOTA references.
• Other program references that can be preserved without ambiguity.
• Core QSO fields and source provenance.

An aggregated WSJT-X type 12 ADIF record may use standard comma-separated POTA reference lists plus bounded application fields for activation identity. A native authenticated gRPC bridge may be considered if lifecycle, edit/delete, or acknowledgement requirements exceed what ADIF-over-UDP can express.

QsoRipper behavior

• Map all references onto one first-class QsoRecord.
• Link to a QsoRipper activation session only through an explicit, documented external-session mapping.
• Preserve unsupported program fields losslessly.
• Replay the canonical handoff idempotently.
• Never infer that separate cross-product records are one contact solely from fuzzy time/call matching.
• Label baseline first-record-only imports honestly until this contract is available.

Upstream dependency

Coordinate a POTACAT change to emit the canonical physical-contact representation and, if available, a stable activation ID. The QsoRipper task remains responsible for documenting the accepted contract and testing its receiver behavior.

Tests

• Two-fer local activation.
• Multiple worked POTA references.
• Local multi-park plus P2P.
• POTA plus SOTA/WWFF cross-program context.
• Replay, restart, and engine switching.
• Confirm one physical contact produces exactly one QsoRipper QSO.

Acceptance criteria

• No valid portable reference is lost in the handoff.
• One physical contact remains one QsoRipper QSO.
• Replays are idempotent.
• Both engines interpret the canonical representation identically.
• The baseline Extra UDP limitation and upstream requirement are documented until complete.