feat(frost/signing): RFC-21 Phase 4.3 -- submit signed snapshots on attempt completion

Wires the three FROST/tbtc-signer receive loops to push their
accumulated evidence into the ROAST coordinator state machine at
end-of-collect. Submission is a deferred call so it runs on both
the success and error return paths.

The orchestration that populates the session-handle binding
(SetCurrentAttemptHandleForSession) is Phase 5 work, so the
submission path is dormant in production deployments today: the
helper sees no binding and returns silently. The code path is
unit-tested via a binding installed by the test itself, so
regressions land at code review.

Files:

* pkg/frost/signing/roast_retry_attempt_handle_default_build.go
  (//go:build !frost_roast_retry)
  - SetCurrentAttemptHandleForSession,
    ClearCurrentAttemptHandleForSession,
    ResetSessionHandleRegistryForTest, and
    currentAttemptHandleForCollect are no-op / always-false stubs.

* pkg/frost/signing/roast_retry_attempt_handle_frost_roast_retry.go
  (//go:build frost_roast_retry)
  - sync.RWMutex-protected map from sessionID to
    sessionAttemptBinding{handle, context}.
  - Set / Clear / Reset functions; later-binding-wins by design
    (a session whose attempt has transitioned re-binds).

* pkg/frost/signing/roast_retry_submit.go
  - submitSnapshotIfActive(sessionID, recorder): no-op unless all
    of (registry populated, session bound, recorder non-empty);
    when all three hold, builds a signed LocalEvidenceSnapshot and
    calls Coordinator.RecordEvidence. Errors logged at WARN, never
    propagated, so a transient submission failure cannot break
    the signing flow.
  - buildSignedSnapshot helper isolates the canonicalisation +
    signing chain so failures are surfaced precisely in logs.

* native_frost_protocol_frost_native.go (round-one + round-two
  callers) and
  native_ffi_primitive_transitional_frost_native.go (tbtc-signer
  contribution caller)
  - Capture the recorder by name (no longer inline).
  - defer submitSnapshotIfActive(request.SessionID, recorder)
    before calling collect, so submission runs on both success and
    error returns.

Tests (7 cases in roast_retry_submit_frost_roast_retry_test.go,
plus the default-build path is exercised by existing tests):

* submit no-op when registry empty
* submit no-op when session unbound
* submit no-op when recorder snapshot is empty
* submit signed snapshot with the right SenderID, signed
  payload, and overflow contents when bound + populated
* SetCurrentAttemptHandleForSession: later binding overwrites
  earlier
* Clear removes the binding
* RecordEvidence error is logged, not propagated; caller does not
  observe failure

All pass under: go test ./pkg/frost/signing/..., go test -tags
'frost_roast_retry' ./pkg/frost/signing/..., go test -race -tags
'frost_native frost_tbtc_signer frost_roast_retry'
./pkg/frost/signing/..., staticcheck -checks '-SA1019'
./pkg/frost/..., gofmt -l ./pkg/frost/signing/, go vet
./pkg/frost/....

Stacked on Phase 4.2 (#3973). Phase 4.4 will add the soak /
fault-injection harness.

Author: mswilkison

pkg/frost/signing/native_ffi_primitive_transitional_frost_native.go

@@ -861,15 +861,19 @@ func buildTaggedTBTCSignerRoundContributions(
 		return nil, fmt.Errorf("cannot send round contribution message: [%w]", err)
 	}
 
-	// RFC-21 Phase 4.2: recorder comes from the roast-retry
-	// registry. NoOp fallback when nothing is registered preserves
-	// Phase 2 receive semantics.
+	// RFC-21 Phase 4.2/4.3: recorder comes from the roast-retry
+	// registry; deferred submission pushes the snapshot into
+	// Coordinator.RecordEvidence at end-of-collect. NoOp fallback
+	// when nothing is registered preserves Phase 2 receive
+	// semantics.
+	contributionsRecorder := roastRetryRecorderForCollect()
+	defer submitSnapshotIfActive(request.SessionID, contributionsRecorder)
 	peerMessages, err := collectBuildTaggedTBTCSignerRoundContributionMessages(
 		ctx,
 		request,
 		includedMembersSet,
 		includedMembersIndexes,
-		roastRetryRecorderForCollect(),
+		contributionsRecorder,
 	)
 	if err != nil {
 		return nil, err

pkg/frost/signing/native_frost_protocol_frost_native.go

@@ -350,21 +350,23 @@ func executeNativeFROSTSigning(
 		return nil, fmt.Errorf("cannot send native FROST round one message: [%w]", err)
 	}
 
-	// RFC-21 Phase 4.2: the recorder comes from the per-process
+	// RFC-21 Phase 4.2/4.3: the recorder comes from the per-process
 	// roast-retry registry. When the registry is empty (default
 	// build, or no caller has registered a coordinator), the helper
 	// returns attempt.NoOpRecorder() and behaviour matches Phase 2.
 	// When the registry has a coordinator, the helper returns a
 	// fresh BoundedRecorder so overflow drops at the receive
-	// callback are captured. PR 4.3 will read this recorder's
-	// Snapshot at end-of-collect and submit the result via
-	// Coordinator.RecordEvidence.
+	// callback are captured. The deferred submitSnapshotIfActive
+	// reads the recorder's Snapshot at end-of-collect and submits
+	// the result via Coordinator.RecordEvidence.
+	roundOneRecorder := roastRetryRecorderForCollect()
+	defer submitSnapshotIfActive(request.SessionID, roundOneRecorder)
 	roundOneMessages, err := collectNativeFROSTRoundOneMessages(
 		ctx,
 		request,
 		includedMembersSet,
 		includedMembersIndexes,
-		roastRetryRecorderForCollect(),
+		roundOneRecorder,
 	)
 	if err != nil {
 		return nil, err
@@ -440,13 +442,16 @@ func executeNativeFROSTSigning(
 		return nil, fmt.Errorf("cannot send native FROST round two message: [%w]", err)
 	}
 
-	// RFC-21 Phase 4.2 recorder source -- see round-one caller above.
+	// RFC-21 Phase 4.2/4.3 recorder source + deferred submission --
+	// see round-one caller above.
+	roundTwoRecorder := roastRetryRecorderForCollect()
+	defer submitSnapshotIfActive(request.SessionID, roundTwoRecorder)
 	roundTwoMessages, err := collectNativeFROSTRoundTwoMessages(
 		ctx,
 		request,
 		includedMembersSet,
 		includedMembersIndexes,
-		roastRetryRecorderForCollect(),
+		roundTwoRecorder,
 	)
 	if err != nil {
 		return nil, err

pkg/frost/signing/roast_retry_attempt_handle_default_build.go

@@ -0,0 +1,36 @@
+//go:build !frost_roast_retry
+
+package signing
+
+import (
+	"github.com/keep-network/keep-core/pkg/frost/roast"
+	"github.com/keep-network/keep-core/pkg/frost/roast/attempt"
+)
+
+// SetCurrentAttemptHandleForSession is a no-op in the default build:
+// the receive loops will never find a handle for any session, so the
+// snapshot submission path is dormant. The build-tagged
+// implementation does the real registration.
+func SetCurrentAttemptHandleForSession(
+	_ string,
+	_ roast.AttemptHandle,
+	_ attempt.AttemptContext,
+) {
+}
+
+// ClearCurrentAttemptHandleForSession is a no-op in the default
+// build.
+func ClearCurrentAttemptHandleForSession(_ string) {}
+
+// ResetSessionHandleRegistryForTest is a no-op in the default
+// build.
+func ResetSessionHandleRegistryForTest() {}
+
+// currentAttemptHandleForCollect always returns ok=false in the
+// default build, so submitSnapshotIfActive exits without attempting
+// the RecordEvidence call.
+func currentAttemptHandleForCollect(
+	_ string,
+) (roast.AttemptHandle, attempt.AttemptContext, bool) {
+	return roast.AttemptHandle{}, attempt.AttemptContext{}, false
+}

pkg/frost/signing/roast_retry_attempt_handle_frost_roast_retry.go

@@ -0,0 +1,82 @@
+//go:build frost_roast_retry
+
+package signing
+
+import (
+	"sync"
+
+	"github.com/keep-network/keep-core/pkg/frost/roast"
+	"github.com/keep-network/keep-core/pkg/frost/roast/attempt"
+)
+
+// sessionAttemptBinding records the current attempt's handle and
+// context for a session. The orchestration layer (Phase 5+) sets
+// the binding via SetCurrentAttemptHandleForSession before driving
+// the round-one / round-two / contribution receive loops; the
+// receive loops read it at end-of-collect to know which attempt to
+// submit their evidence snapshot against.
+type sessionAttemptBinding struct {
+	handle  roast.AttemptHandle
+	context attempt.AttemptContext
+}
+
+var (
+	sessionAttemptBindingMu sync.RWMutex
+	sessionAttemptBindings  = map[string]sessionAttemptBinding{}
+)
+
+// SetCurrentAttemptHandleForSession records the in-flight attempt
+// handle and context for the named session. Callers in the
+// orchestration layer (Phase 5+) invoke this immediately after
+// Coordinator.BeginAttempt so receive loops can correlate their
+// captured evidence with the right attempt.
+//
+// Later calls for the same session overwrite earlier ones (this is
+// the documented behaviour: a session whose attempt has transitioned
+// re-binds to the new attempt's handle).
+func SetCurrentAttemptHandleForSession(
+	sessionID string,
+	handle roast.AttemptHandle,
+	ctx attempt.AttemptContext,
+) {
+	sessionAttemptBindingMu.Lock()
+	defer sessionAttemptBindingMu.Unlock()
+	sessionAttemptBindings[sessionID] = sessionAttemptBinding{
+		handle:  handle,
+		context: ctx,
+	}
+}
+
+// ClearCurrentAttemptHandleForSession removes any binding for the
+// named session. Callers invoke this when a session terminates so
+// the registry does not grow unbounded.
+func ClearCurrentAttemptHandleForSession(sessionID string) {
+	sessionAttemptBindingMu.Lock()
+	defer sessionAttemptBindingMu.Unlock()
+	delete(sessionAttemptBindings, sessionID)
+}
+
+// ResetSessionHandleRegistryForTest clears every binding. Exposed
+// only for tests; not for production code paths.
+func ResetSessionHandleRegistryForTest() {
+	sessionAttemptBindingMu.Lock()
+	defer sessionAttemptBindingMu.Unlock()
+	sessionAttemptBindings = map[string]sessionAttemptBinding{}
+}
+
+// currentAttemptHandleForCollect reads the binding the orchestration
+// layer set for this session. Returns (zero, zero, false) when no
+// binding exists -- the typical Phase-4 state, where no orchestration
+// is wired yet. The submit helper takes ok=false as the signal to
+// skip the RecordEvidence call.
+func currentAttemptHandleForCollect(
+	sessionID string,
+) (roast.AttemptHandle, attempt.AttemptContext, bool) {
+	sessionAttemptBindingMu.RLock()
+	defer sessionAttemptBindingMu.RUnlock()
+	binding, ok := sessionAttemptBindings[sessionID]
+	if !ok {
+		return roast.AttemptHandle{}, attempt.AttemptContext{}, false
+	}
+	return binding.handle, binding.context, true
+}

pkg/frost/signing/roast_retry_submit.go

@@ -0,0 +1,105 @@
+package signing
+
+import (
+	"github.com/ipfs/go-log/v2"
+	"github.com/keep-network/keep-core/pkg/frost/roast"
+	"github.com/keep-network/keep-core/pkg/frost/roast/attempt"
+	"github.com/keep-network/keep-core/pkg/protocol/group"
+)
+
+// roastRetryLogger is the logger the snapshot-submission path uses
+// for non-fatal diagnostics (submission failures, signature errors).
+// A submission failure does not propagate to the signing flow:
+// Phase 4 ships the submission code path unused in production, and
+// even when wired (Phase 5+) a transient submission failure is
+// recoverable by the next attempt's evidence flow.
+var roastRetryLogger = log.Logger("keep-frost-roast-retry")
+
+// submitSnapshotIfActive is invoked at end-of-collect to push the
+// receive loop's accumulated evidence into the ROAST coordinator's
+// RecordEvidence pipeline. The function is a no-op when any of the
+// following is true:
+//
+//   - the ROAST-retry registry is empty (default build, no caller
+//     has invoked RegisterRoastRetryCoordinator);
+//   - no session-handle binding exists for sessionID (the typical
+//     Phase-4 state, where the orchestration layer that calls
+//     SetCurrentAttemptHandleForSession is not yet implemented);
+//   - the recorder is a NoOp (no events were captured).
+//
+// When all three preconditions hold, the function builds a
+// LocalEvidenceSnapshot, signs it with the registered Signer, and
+// submits it via Coordinator.RecordEvidence. Errors at any step are
+// logged at WARN level and otherwise swallowed -- snapshot
+// submission must not break the receive loop's primary signing
+// behaviour.
+func submitSnapshotIfActive(
+	sessionID string,
+	recorder attempt.EvidenceRecorder,
+) {
+	if recorder == nil {
+		return
+	}
+	deps, ok := RegisteredRoastRetryCoordinator()
+	if !ok {
+		return
+	}
+	handle, ctx, ok := currentAttemptHandleForCollect(sessionID)
+	if !ok {
+		return
+	}
+	evidence := recorder.Snapshot()
+	if len(evidence.Overflows) == 0 {
+		// Nothing observed worth submitting; emitting an empty
+		// snapshot is still meaningful in the ROAST protocol
+		// (proof-of-attendance) but adds noise to the bundle.
+		// Phase 4.3 chooses to skip empty submissions; Phase 5
+		// orchestration may revisit this if attestations need to
+		// be unconditional.
+		return
+	}
+	snap := buildSignedSnapshot(deps, ctx, evidence)
+	if snap == nil {
+		return
+	}
+	if err := deps.Coordinator.RecordEvidence(handle, snap); err != nil {
+		roastRetryLogger.Warnf(
+			"roast-retry: RecordEvidence failed for session %q: %v",
+			sessionID,
+			err,
+		)
+	}
+}
+
+// buildSignedSnapshot constructs and signs a LocalEvidenceSnapshot
+// from the captured evidence. Returns nil and logs on signature
+// failure; callers treat nil as "skip submission" and continue.
+func buildSignedSnapshot(
+	deps RoastRetryDeps,
+	ctx attempt.AttemptContext,
+	evidence attempt.Evidence,
+) *roast.LocalEvidenceSnapshot {
+	snap := roast.NewLocalEvidenceSnapshot(
+		group.MemberIndex(deps.SelfMember),
+		ctx.Hash(),
+		evidence,
+	)
+	payload, err := roast.CanonicalSnapshotBytes(snap)
+	if err != nil {
+		roastRetryLogger.Warnf(
+			"roast-retry: canonicalising snapshot failed: %v",
+			err,
+		)
+		return nil
+	}
+	sig, err := deps.Signer.Sign(payload)
+	if err != nil {
+		roastRetryLogger.Warnf(
+			"roast-retry: signing snapshot failed: %v",
+			err,
+		)
+		return nil
+	}
+	snap.OperatorSignature = sig
+	return snap
+}