feat: serialize keyed tasks across queues with durable fencing tokens

pulse/service/history.go

@@ -19,18 +19,19 @@ type HistoryPageInput struct {
 
 // AttemptSummary 是执行尝试的查询快照，不提供当前执行授权。
 type AttemptSummary struct {
-	ID           core.ID            `json:"id"`                      // ID 尝试标识，不是执行秘密。
-	TaskID       core.ID            `json:"task_id"`                 // TaskID 所属任务；查询始终限定在该任务下。
-	Epoch        uint64             `json:"epoch,string"`            // Epoch 单任务执行代次，JSON 为十进制字符串。
-	State        pulse.AttemptState `json:"state"`                   // State 尝试状态，与整个任务状态分开。
-	Revision     uint64             `json:"revision,string"`         // Revision 当前记录版本，可因续租/恢复变化。
-	LeaseUntil   time.Time          `json:"lease_until"`             // LeaseUntil 数据库记录的租约期限；查询不能授权业务执行。
-	AuthorizedAt *time.Time         `json:"authorized_at,omitempty"` // AuthorizedAt 开始批准时间；空表示未批准，不证明副作用已经发生。
-	EndedAt      *time.Time         `json:"ended_at,omitempty"`      // EndedAt 尝试结束时间；仍在执行时为空。
-	Retryable    bool               `json:"retryable,omitempty"`     // Retryable 该明确失败报告是否声明可安全重试；不代表平台必定安排重试。
-	ErrorCode    string             `json:"error_code,omitempty"`    // ErrorCode 稳定错误分类；无错误时为空。
-	CreatedAt    time.Time          `json:"created_at"`              // CreatedAt 创建时间，UTC 微秒精度。
-	UpdatedAt    time.Time          `json:"updated_at"`              // UpdatedAt 最新变更时间，不能代替版本校验。
+	ConcurrencyToken uint64             `json:"concurrency_token,omitempty,string"` // ConcurrencyToken 资源键的单调许可序号；无资源键时为零，不能代替当前授权。
+	ID               core.ID            `json:"id"`                                 // ID 尝试标识，不是执行秘密。
+	TaskID           core.ID            `json:"task_id"`                            // TaskID 所属任务；查询始终限定在该任务下。
+	Epoch            uint64             `json:"epoch,string"`                       // Epoch 单任务执行代次，JSON 为十进制字符串。
+	State            pulse.AttemptState `json:"state"`                              // State 尝试状态，与整个任务状态分开。
+	Revision         uint64             `json:"revision,string"`                    // Revision 当前记录版本，可因续租/恢复变化。
+	LeaseUntil       time.Time          `json:"lease_until"`                        // LeaseUntil 数据库记录的租约期限；查询不能授权业务执行。
+	AuthorizedAt     *time.Time         `json:"authorized_at,omitempty"`            // AuthorizedAt 开始批准时间；空表示未批准，不证明副作用已经发生。
+	EndedAt          *time.Time         `json:"ended_at,omitempty"`                 // EndedAt 尝试结束时间；仍在执行时为空。
+	Retryable        bool               `json:"retryable,omitempty"`                // Retryable 该明确失败报告是否声明可安全重试；不代表平台必定安排重试。
+	ErrorCode        string             `json:"error_code,omitempty"`               // ErrorCode 稳定错误分类；无错误时为空。
+	CreatedAt        time.Time          `json:"created_at"`                         // CreatedAt 创建时间，UTC 微秒精度。
+	UpdatedAt        time.Time          `json:"updated_at"`                         // UpdatedAt 最新变更时间，不能代替版本校验。
 }
 
 // AttemptView 增加当前归属与已保存结果，不返回令牌、摘要或原始请求秘密。

pulse/service/service.go

@@ -6,6 +6,7 @@ import (
 	"regexp"
 	"strings"
 	"time"
+	"unicode"
 	"unicode/utf8"
 
 	"git.yuntuo.hk/k2safe/orbit/internal/fault"
@@ -51,6 +52,9 @@ func NormalizeSubmit(in SubmitInput) (SubmitInput, error) {
 	if !utf8.ValidString(in.BusinessKey) || utf8.RuneCountInString(in.BusinessKey) > 191 || strings.ContainsAny(in.BusinessKey, "\x00\r\n") {
 		return in, fault.Invalid("business_key must be at most 191 characters without control newlines")
 	}
+	if err := ValidateConcurrencyKey(in.ConcurrencyKey); err != nil {
+		return in, err
+	}
 	if in.TaskTimeoutMS == 0 {
 		in.TaskTimeoutMS = 24 * 60 * 60 * 1000
 	}
@@ -170,3 +174,19 @@ func (s *Service) ConfigureQueue(ctx context.Context, token auth.Token, id core.
 	}
 	return s.store.ConfigureQueue(ctx, token, id, key, in)
 }
+
+// ValidateConcurrencyKey 不归一化资源键，字节精确相等才共享许可。
+func ValidateConcurrencyKey(key string) error {
+	if key == "" {
+		return nil
+	}
+	if !utf8.ValidString(key) || utf8.RuneCountInString(key) > 191 || strings.TrimSpace(key) != key {
+		return fault.Invalid("invalid concurrency_key")
+	}
+	for _, c := range key {
+		if unicode.IsControl(c) {
+			return fault.Invalid("invalid concurrency_key")
+		}
+	}
+	return nil
+}

pulse/service/types.go

@@ -25,6 +25,8 @@ type SubmitInput struct {
 	Payload json.RawMessage `json:"payload"`
 	// BusinessKey 可选关联键，不提供业务效果幂等保证。
 	BusinessKey string `json:"business_key,omitempty"`
+	// ConcurrencyKey 显式互斥资源键，同命名空间跨队列最多一个有效尝试；不代替业务幂等。
+	ConcurrencyKey string `json:"concurrency_key,omitempty"`
 	// AvailableAt 最早执行时间；为空表示受理后即可进入派发范围。
 	AvailableAt *time.Time `json:"available_at,omitempty"`
 	// StartDeadlineAt 最晚开始时间；为空表示使用任务总截止时间。
@@ -63,6 +65,8 @@ type TaskView struct {
 	EffectUncertain bool `json:"effect_uncertain,omitempty"`
 	// BusinessKey 可选业务关联键，不自动提供业务效果幂等。
 	BusinessKey string `json:"business_key,omitempty"`
+	// ConcurrencyKey 显式互斥资源键，同命名空间跨队列最多一个有效尝试；不代替业务幂等。
+	ConcurrencyKey string `json:"concurrency_key,omitempty"`
 	// AvailableAt 最早可执行时间，UTC。
 	AvailableAt time.Time `json:"available_at"`
 	// StartDeadlineAt 最晚开始时间；为空时使用任务总截止时间。
@@ -131,6 +135,8 @@ type TaskSummary struct {
 	EffectUncertain bool `json:"effect_uncertain,omitempty"`
 	// BusinessKey 可选业务关联键，不自动提供业务效果幂等。
 	BusinessKey string `json:"business_key,omitempty"`
+	// ConcurrencyKey 显式互斥资源键，同命名空间跨队列最多一个有效尝试；不代替业务幂等。
+	ConcurrencyKey string `json:"concurrency_key,omitempty"`
 	// AvailableAt 最早可执行时间，UTC。
 	AvailableAt time.Time `json:"available_at"`
 	// DeadlineAt 任务总截止时间，UTC。