feat(common): add an optional claim reader to the attempt journal

CHANGELOG.md

@@ -32,6 +32,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/).
 
 ### Added
 
+- **`pkg`:** optional `common.ClaimReader` (`ClaimedByOthers(ctx, token, ids)`), which an `AttemptJournal` may implement so a provider can skip commitments another purchase recorded as bought (#700).
 - **`pkg`:** `common.Commitment.CostKnown` reports whether `Cost` holds a price the provider reported. The zero value means unknown, so a `Cost` of 0 without `CostKnown` must not be read as free. Producers set it in a follow-up (#74).
 
 - **`common`:** `AttemptJournal`, `AttemptRecord` and an optional `PurchaseOptions.AttemptJournal`, a caller-backed durable record of purchase attempts per idempotency token (#107). Nothing reads it yet.

pkg/common/attempt_journal.go

@@ -74,3 +74,15 @@ type AttemptJournal interface {
 	PriorAttempts(ctx context.Context, token string) ([]AttemptRecord, error)
 	RecordAttempt(ctx context.Context, rec AttemptRecord) error
 }
+
+// ClaimReader is an optional interface an AttemptJournal may also implement
+// (go#700). A provider client finds it by type assertion on
+// PurchaseOptions.AttemptJournal; a journal without it behaves as before.
+//
+// ClaimedByOthers returns the subset of ids that some attempt under a token
+// other than token has recorded as purchased. An id that only the given token
+// recorded is not returned, and an empty result excludes nothing. Any error
+// means the claims are not known.
+type ClaimReader interface {
+	ClaimedByOthers(ctx context.Context, token string, ids []string) ([]string, error)
+}

pkg/common/types.go

@@ -470,6 +470,9 @@ type PurchaseOptions struct {
 	// Only Redshift reads it, honored by providers/aws from the follow-up
 	// change onward; other providers ignore it. Used only with a non-empty
 	// IdempotencyToken; see AttemptJournal for the caller contract.
+	// A journal that also implements the optional ClaimReader lets Redshift
+	// skip nodes another purchase recorded, from the follow-up change to
+	// providers/aws onward (go#700).
 	AttemptJournal AttemptJournal
 
 	// OfferingClass is the EC2 Reserved Instance offering class for this