@stackonward/cli 0.0.1 → 1.0.1

package/dist/resources/templates/go-backend/internal/core/commandreplay/service.go

@@ -0,0 +1,853 @@
+package commandreplay
+
+import (
+	"bytes"
+	"context"
+	"crypto/rand"
+	"crypto/sha256"
+	"crypto/subtle"
+	"encoding/base64"
+	"encoding/hex"
+	"encoding/json"
+	"errors"
+	"strings"
+	"time"
+	"unicode/utf8"
+
+	"{{module}}/internal/common/canonicaljson"
+	"{{module}}/internal/core/database"
+	"{{module}}/pkg/apierror"
+)
+
+const (
+	defaultCommandReplayTTL = 24 * time.Hour
+
+	maxNamespaceLength             = 200
+	maxCommandScopeLength          = 128
+	maxIdempotencyKeyLength        = 191
+	maxPrincipalTypeLength         = 32
+	maxPrincipalRefLength          = 64
+	maxErrorCodeLength             = 120
+	maxExternalReferenceTypeLength = 64
+	maxExternalReferenceNoLength   = 191
+
+	errCodeCommandReplayConflict    = "command_replay_conflict"
+	errCodeCommandReplayInProgress  = "command_replay_in_progress"
+	errCodeCommandReplayExpired     = "command_replay_expired"
+	commandReplayExecutionTokenSize = 32
+	maxExternalLeaseTTL             = 15 * time.Minute
+	maxExternalRecoveryBatchSize    = 500
+)
+
+// CommandReplayService 提供跨领域命令共享的幂等回放契约。
+type CommandReplayService struct {
+	repo      CommandReplayRepository
+	txManager *database.TransactionManager
+	now       func() time.Time
+}
+
+// NewCommandReplayService 创建命令幂等回放服务。
+func NewCommandReplayService(repo CommandReplayRepository, txManager *database.TransactionManager) *CommandReplayService {
+	return &CommandReplayService{
+		repo:      repo,
+		txManager: txManager,
+		now:       func() time.Time { return time.Now().UTC() },
+	}
+}
+
+// Execute 在同一命令事务内完成幂等注册、业务执行和终态持久化。
+func (s *CommandReplayService) Execute(ctx context.Context, req CommandReplayBeginRequest, fn CommandReplayExecuteFunc) (*CommandReplayExecuteResult, error) {
+	var result *CommandReplayExecuteResult
+	var terminalBusinessErr error
+
+	err := s.withTransaction(ctx, func(txCtx context.Context) error {
+		normalized, normalizeErr := normalizeCommandReplayBeginRequest(req)
+		if normalizeErr != nil {
+			return normalizeErr
+		}
+		if fn == nil {
+			return apierror.Internal("Command replay execute function is required")
+		}
+
+		now := s.now().UTC()
+		expiresAt := now.Add(normalized.ttl)
+		acquired, lockErr := s.repo.TryAcquireScopeLock(
+			txCtx,
+			normalized.namespace,
+			normalized.commandScope,
+			normalized.idempotencyKey,
+		)
+		if lockErr != nil {
+			return apierror.Internal("Failed to acquire command replay scope lock")
+		}
+		if !acquired {
+			return apierror.Conflict(errCodeCommandReplayInProgress, "Command replay is already in progress")
+		}
+
+		existing, findErr := s.repo.FindByScope(
+			txCtx,
+			normalized.namespace,
+			normalized.commandScope,
+			normalized.idempotencyKey,
+		)
+		if findErr != nil {
+			return apierror.Internal("Failed to load command replay record")
+		}
+		if existing != nil {
+			classified, classifyErr := classifyCommandReplayRecord(existing, normalized.requestHash, now)
+			if classifyErr != nil {
+				return classifyErr
+			}
+			result = classified
+			if replayErr, replayErrBuildErr := commandReplayBusinessErrorFromRecord(existing); replayErrBuildErr != nil {
+				return replayErrBuildErr
+			} else if replayErr != nil {
+				terminalBusinessErr = replayErr
+			}
+			return nil
+		}
+
+		record := &CommandReplayRecord{
+			Namespace:       normalized.namespace,
+			CommandScope:    normalized.commandScope,
+			IdempotencyKey:  normalized.idempotencyKey,
+			RequestHash:     normalized.requestHash,
+			PrincipalType:   cloneStringPtr(normalized.principalType),
+			PrincipalRef:    cloneStringPtr(normalized.principalRef),
+			Status:          CommandReplayStatusStarted,
+			ResponsePayload: json.RawMessage(`{}`),
+			ExpiresAt:       expiresAt,
+			Metadata:        normalized.metadata,
+		}
+		if createErr := s.repo.Create(txCtx, record); createErr != nil {
+			if !isCommandReplayDuplicateCreateError(createErr) {
+				return apierror.Internal("Failed to create command replay record")
+			}
+			duplicate, reloadErr := s.repo.FindByScope(
+				txCtx,
+				normalized.namespace,
+				normalized.commandScope,
+				normalized.idempotencyKey,
+			)
+			if reloadErr != nil {
+				return apierror.Internal("Failed to load command replay record")
+			}
+			if duplicate == nil {
+				return apierror.Internal("Command replay record was not found after duplicate insert")
+			}
+			classified, classifyErr := classifyCommandReplayRecord(duplicate, normalized.requestHash, now)
+			if classifyErr != nil {
+				return classifyErr
+			}
+			result = classified
+			if replayErr, replayErrBuildErr := commandReplayBusinessErrorFromRecord(duplicate); replayErrBuildErr != nil {
+				return replayErrBuildErr
+			} else if replayErr != nil {
+				terminalBusinessErr = replayErr
+			}
+			return nil
+		}
+
+		commandResult, executeErr := fn(txCtx, record)
+		if executeErr != nil {
+			return executeErr
+		}
+		normalizedResult, resultErr := normalizeCommandReplayCommandResult(commandResult)
+		if resultErr != nil {
+			return resultErr
+		}
+
+		completedAt := s.now().UTC()
+		switch normalizedResult.status {
+		case CommandReplayStatusSucceeded:
+			if markErr := s.markSucceeded(txCtx, record.ID, normalizedResult.responsePayload, completedAt); markErr != nil {
+				return markErr
+			}
+		case CommandReplayStatusFailed:
+			if markErr := s.markFailed(txCtx, record.ID, normalizedResult.errorCode, normalizedResult.errorStatus, normalizedResult.responsePayload, completedAt); markErr != nil {
+				return markErr
+			}
+			terminalBusinessErr = normalizedResult.returnError
+		default:
+			return apierror.Internal("Command replay result has invalid status")
+		}
+
+		record.Status = normalizedResult.status
+		record.ResponsePayload = append(json.RawMessage(nil), normalizedResult.responsePayload...)
+		record.CompletedAt = cloneTimePtr(&completedAt)
+		if normalizedResult.status == CommandReplayStatusFailed {
+			record.ErrorCode = cloneStringPtr(&normalizedResult.errorCode)
+			record.ErrorStatus = cloneIntPtr(&normalizedResult.errorStatus)
+		}
+		result = &CommandReplayExecuteResult{
+			Record:          record,
+			Replayed:        false,
+			ResponsePayload: normalizedResult.responsePayload,
+			ErrorCode:       cloneStringPtr(record.ErrorCode),
+			ErrorStatus:     cloneIntPtr(record.ErrorStatus),
+			Status:          normalizedResult.status,
+		}
+		return nil
+	})
+	if err != nil {
+		return nil, err
+	}
+	if terminalBusinessErr != nil {
+		return result, terminalBusinessErr
+	}
+	return result, nil
+}
+
+// BeginExternal 原子创建回放记录、业务预留和首次执行租约。
+func (s *CommandReplayService) BeginExternal(
+	ctx context.Context,
+	req CommandReplayBeginRequest,
+	leaseTTL time.Duration,
+	reserve CommandReplayExternalBeginFunc,
+) (*CommandReplayExternalLease, error) {
+	normalized, err := normalizeCommandReplayBeginRequest(req)
+	if err != nil {
+		return nil, err
+	}
+	if err := validateExternalLeaseTTL(leaseTTL); err != nil {
+		return nil, err
+	}
+	if reserve == nil {
+		return nil, apierror.Internal("External command reservation function is required")
+	}
+
+	var lease *CommandReplayExternalLease
+	err = s.withTransaction(ctx, func(txCtx context.Context) error {
+		now := s.now().UTC()
+		acquired, lockErr := s.repo.TryAcquireScopeLock(txCtx, normalized.namespace, normalized.commandScope, normalized.idempotencyKey)
+		if lockErr != nil {
+			return apierror.Internal("Failed to acquire command replay scope lock")
+		}
+		if !acquired {
+			return apierror.Conflict(errCodeCommandReplayInProgress, "Command replay is already in progress")
+		}
+		existing, findErr := s.repo.FindByScope(txCtx, normalized.namespace, normalized.commandScope, normalized.idempotencyKey)
+		if findErr != nil {
+			return apierror.Internal("Failed to load command replay record")
+		}
+		if existing != nil {
+			if !existing.MatchesRequestHash(normalized.requestHash) {
+				return apierror.Conflict(errCodeCommandReplayConflict, "Idempotency key was reused with a different request payload")
+			}
+			if existing.Status.IsTerminal() {
+				replayed, classifyErr := classifyCommandReplayRecord(existing, normalized.requestHash, now)
+				if classifyErr != nil {
+					return classifyErr
+				}
+				lease = &CommandReplayExternalLease{RecordID: existing.ID, Replayed: replayed}
+				return nil
+			}
+			if existing.Status != CommandReplayStatusStarted || !existing.HasExternalReservation() || existing.ExternalNextRecoveryAt == nil {
+				return apierror.Internal("External command replay record is incomplete")
+			}
+			if existing.HasActiveExternalLease(now) || now.Before(*existing.ExternalNextRecoveryAt) {
+				return apierror.Conflict(errCodeCommandReplayInProgress, "Command replay is already in progress")
+			}
+			executionToken, tokenHash, tokenErr := newCommandReplayExecutionToken()
+			if tokenErr != nil {
+				return apierror.Internal("Failed to create external command execution lease")
+			}
+			leaseExpiresAt := now.Add(leaseTTL)
+			if claimErr := s.repo.ClaimExternalRecovery(txCtx, existing.ID, *existing.ExternalNextRecoveryAt, tokenHash, leaseExpiresAt); claimErr != nil {
+				return apierror.Conflict(errCodeCommandReplayInProgress, "External command recovery lease is unavailable")
+			}
+			lease = externalLeaseFromRecord(existing, executionToken, existing.ExternalAttemptCount+1)
+			return nil
+		}
+
+		record := newCommandReplayRecord(normalized, now)
+		if createErr := s.repo.Create(txCtx, record); createErr != nil {
+			return apierror.Internal("Failed to create command replay record")
+		}
+		reservation, reserveErr := reserve(txCtx, record)
+		if reserveErr != nil {
+			return reserveErr
+		}
+		reservation, reservationErr := normalizeExternalReservation(reservation)
+		if reservationErr != nil {
+			return reservationErr
+		}
+		executionToken, tokenHash, tokenErr := newCommandReplayExecutionToken()
+		if tokenErr != nil {
+			return apierror.Internal("Failed to create external command execution lease")
+		}
+		leaseExpiresAt := now.Add(leaseTTL)
+		if startErr := s.repo.StartExternalExecution(
+			txCtx,
+			record.ID,
+			reservation.ReferenceType,
+			reservation.ReferenceNo,
+			tokenHash,
+			reservation.PreparedResponsePayload,
+			leaseExpiresAt,
+		); startErr != nil {
+			return apierror.Internal("Failed to persist external command execution lease")
+		}
+		record.ResponsePayload = append(json.RawMessage(nil), reservation.PreparedResponsePayload...)
+		lease = &CommandReplayExternalLease{
+			RecordID: record.ID, ExecutionToken: executionToken, Reservation: reservation, AttemptCount: 1,
+		}
+		return nil
+	})
+	if err != nil {
+		return nil, err
+	}
+	return lease, nil
+}
+
+// ClaimExternalRecovery 领取已到期外部执行记录的新租约。
+func (s *CommandReplayService) ClaimExternalRecovery(
+	ctx context.Context,
+	recordID int64,
+	leaseTTL time.Duration,
+) (*CommandReplayExternalLease, error) {
+	if recordID <= 0 {
+		return nil, apierror.BadRequest(apierror.CodeValidationFailed, "recordID must be positive")
+	}
+	if err := validateExternalLeaseTTL(leaseTTL); err != nil {
+		return nil, err
+	}
+	var lease *CommandReplayExternalLease
+	err := s.withTransaction(ctx, func(txCtx context.Context) error {
+		now := s.now().UTC()
+		record, findErr := s.repo.FindByIDForUpdate(txCtx, recordID)
+		if findErr != nil {
+			return apierror.Internal("Failed to load external command replay record")
+		}
+		if record == nil || record.Status != CommandReplayStatusStarted || !record.HasExternalReservation() || record.ExternalNextRecoveryAt == nil {
+			return apierror.NotFound("External command recovery was not found")
+		}
+		if record.HasActiveExternalLease(now) || now.Before(*record.ExternalNextRecoveryAt) {
+			return apierror.Conflict(errCodeCommandReplayInProgress, "External command recovery lease is unavailable")
+		}
+		executionToken, tokenHash, tokenErr := newCommandReplayExecutionToken()
+		if tokenErr != nil {
+			return apierror.Internal("Failed to create external command recovery lease")
+		}
+		if claimErr := s.repo.ClaimExternalRecovery(txCtx, record.ID, *record.ExternalNextRecoveryAt, tokenHash, now.Add(leaseTTL)); claimErr != nil {
+			return apierror.Conflict(errCodeCommandReplayInProgress, "External command recovery lease is unavailable")
+		}
+		lease = externalLeaseFromRecord(record, executionToken, record.ExternalAttemptCount+1)
+		return nil
+	})
+	if err != nil {
+		return nil, err
+	}
+	return lease, nil
+}
+
+// CompleteExternal 使用当前租约提交非敏感回放结果。
+func (s *CommandReplayService) CompleteExternal(
+	ctx context.Context,
+	recordID int64,
+	executionToken string,
+	complete CommandReplayExternalCompleteFunc,
+) (*CommandReplayExecuteResult, error) {
+	if recordID <= 0 || complete == nil {
+		return nil, apierror.BadRequest(apierror.CodeValidationFailed, "external completion input is invalid")
+	}
+	tokenHash, err := commandReplayExecutionTokenHash(executionToken)
+	if err != nil {
+		return nil, err
+	}
+	var result *CommandReplayExecuteResult
+	var terminalBusinessErr error
+	err = s.withTransaction(ctx, func(txCtx context.Context) error {
+		now := s.now().UTC()
+		record, findErr := s.repo.FindByIDForUpdate(txCtx, recordID)
+		if findErr != nil {
+			return apierror.Internal("Failed to load external command replay record")
+		}
+		if !hasCurrentExternalLease(record, tokenHash, now) {
+			return apierror.Conflict(errCodeCommandReplayInProgress, "External command execution lease is invalid or expired")
+		}
+		commandResult, completeErr := complete(txCtx, record)
+		if completeErr != nil {
+			return completeErr
+		}
+		normalizedResult, normalizeErr := normalizeCommandReplayCommandResult(commandResult)
+		if normalizeErr != nil {
+			return normalizeErr
+		}
+		if clearErr := s.repo.ClearExternalExecution(txCtx, record.ID, tokenHash); clearErr != nil {
+			return apierror.Internal("Failed to clear external command execution lease")
+		}
+		completedAt := s.now().UTC()
+		switch normalizedResult.status {
+		case CommandReplayStatusSucceeded:
+			if markErr := s.markSucceeded(txCtx, record.ID, normalizedResult.responsePayload, completedAt); markErr != nil {
+				return markErr
+			}
+		case CommandReplayStatusFailed:
+			if markErr := s.markFailed(txCtx, record.ID, normalizedResult.errorCode, normalizedResult.errorStatus, normalizedResult.responsePayload, completedAt); markErr != nil {
+				return markErr
+			}
+			terminalBusinessErr = normalizedResult.returnError
+		default:
+			return apierror.Internal("External command completion has invalid status")
+		}
+		record.Status = normalizedResult.status
+		record.ResponsePayload = append(json.RawMessage(nil), normalizedResult.responsePayload...)
+		record.CompletedAt = cloneTimePtr(&completedAt)
+		record.ExternalReferenceType = nil
+		record.ExternalReferenceNo = nil
+		record.ExecutionTokenHash = nil
+		record.LeaseExpiresAt = nil
+		record.ExternalNextRecoveryAt = nil
+		record.ExternalAttemptCount = 0
+		record.ExternalLastErrorCode = nil
+		if normalizedResult.status == CommandReplayStatusFailed {
+			record.ErrorCode = cloneStringPtr(&normalizedResult.errorCode)
+			record.ErrorStatus = cloneIntPtr(&normalizedResult.errorStatus)
+		}
+		result = &CommandReplayExecuteResult{
+			Record: record, ResponsePayload: normalizedResult.responsePayload, ErrorCode: cloneStringPtr(record.ErrorCode),
+			ErrorStatus: cloneIntPtr(record.ErrorStatus), Status: normalizedResult.status,
+		}
+		return nil
+	})
+	if err != nil {
+		return nil, err
+	}
+	if terminalBusinessErr != nil {
+		return result, terminalBusinessErr
+	}
+	return result, nil
+}
+
+// DeferExternal 记录可重试分类并安排下一次查询。
+func (s *CommandReplayService) DeferExternal(
+	ctx context.Context,
+	recordID int64,
+	executionToken string,
+	errorCode string,
+	nextRecoveryAt time.Time,
+) error {
+	return s.deferExternal(ctx, recordID, executionToken, errorCode, nextRecoveryAt, nil)
+}
+
+// DeferExternalWith 在同一事务内校验租约、提交业务恢复状态并安排下一次查询。
+func (s *CommandReplayService) DeferExternalWith(
+	ctx context.Context,
+	recordID int64,
+	executionToken string,
+	errorCode string,
+	nextRecoveryAt time.Time,
+	deferFn CommandReplayExternalDeferFunc,
+) error {
+	if deferFn == nil {
+		return apierror.Internal("External command defer callback is required")
+	}
+	return s.deferExternal(ctx, recordID, executionToken, errorCode, nextRecoveryAt, deferFn)
+}
+
+func (s *CommandReplayService) deferExternal(
+	ctx context.Context,
+	recordID int64,
+	executionToken string,
+	errorCode string,
+	nextRecoveryAt time.Time,
+	deferFn CommandReplayExternalDeferFunc,
+) error {
+	if recordID <= 0 {
+		return apierror.BadRequest(apierror.CodeValidationFailed, "recordID must be positive")
+	}
+	normalizedErrorCode, err := normalizeRequiredString("errorCode", errorCode, maxErrorCodeLength)
+	if err != nil {
+		return err
+	}
+	tokenHash, err := commandReplayExecutionTokenHash(executionToken)
+	if err != nil {
+		return err
+	}
+	return s.withTransaction(ctx, func(txCtx context.Context) error {
+		now := s.now().UTC()
+		if !nextRecoveryAt.After(now) {
+			return apierror.BadRequest(apierror.CodeValidationFailed, "nextRecoveryAt must be in the future")
+		}
+		record, findErr := s.repo.FindByIDForUpdate(txCtx, recordID)
+		if findErr != nil {
+			return apierror.Internal("Failed to load external command replay record")
+		}
+		if !hasCurrentExternalLease(record, tokenHash, now) {
+			return apierror.Conflict(errCodeCommandReplayInProgress, "External command execution lease is invalid or expired")
+		}
+		if deferFn != nil {
+			if deferErr := deferFn(txCtx, record); deferErr != nil {
+				return deferErr
+			}
+		}
+		if deferErr := s.repo.DeferExternalExecution(txCtx, recordID, tokenHash, normalizedErrorCode, nextRecoveryAt.UTC()); deferErr != nil {
+			return apierror.Conflict(errCodeCommandReplayInProgress, "External command execution lease is invalid or expired")
+		}
+		return nil
+	})
+}
+
+// ListDueExternalRecoveries 有界列出已到期且无有效租约的记录。
+func (s *CommandReplayService) ListDueExternalRecoveries(
+	ctx context.Context,
+	referenceType string,
+	at time.Time,
+	limit int,
+) ([]CommandReplayRecord, error) {
+	normalizedReferenceType, err := normalizeRequiredString("referenceType", referenceType, maxExternalReferenceTypeLength)
+	if err != nil {
+		return nil, err
+	}
+	if limit < 1 || limit > maxExternalRecoveryBatchSize {
+		return nil, apierror.BadRequest(apierror.CodeValidationFailed, "limit must be between 1 and 500")
+	}
+	records, err := s.repo.ListDueExternalRecoveries(ctx, normalizedReferenceType, at.UTC(), limit)
+	if err != nil {
+		return nil, apierror.Internal("Failed to list due external command recoveries")
+	}
+	return records, nil
+}
+
+func newCommandReplayRecord(normalized *normalizedCommandReplayBeginRequest, now time.Time) *CommandReplayRecord {
+	return &CommandReplayRecord{
+		Namespace: normalized.namespace, CommandScope: normalized.commandScope,
+		IdempotencyKey: normalized.idempotencyKey, RequestHash: normalized.requestHash,
+		PrincipalType: cloneStringPtr(normalized.principalType), PrincipalRef: cloneStringPtr(normalized.principalRef),
+		Status: CommandReplayStatusStarted, ResponsePayload: json.RawMessage(`{}`),
+		ExpiresAt: now.Add(normalized.ttl), Metadata: normalized.metadata,
+	}
+}
+
+func normalizeExternalReservation(reservation CommandReplayExternalReservation) (CommandReplayExternalReservation, error) {
+	referenceType, err := normalizeRequiredString("referenceType", reservation.ReferenceType, maxExternalReferenceTypeLength)
+	if err != nil {
+		return CommandReplayExternalReservation{}, err
+	}
+	referenceNo, err := normalizeRequiredString("referenceNo", reservation.ReferenceNo, maxExternalReferenceNoLength)
+	if err != nil {
+		return CommandReplayExternalReservation{}, err
+	}
+	preparedResponsePayload, err := canonicalRawJSONObject(reservation.PreparedResponsePayload, true)
+	if err != nil {
+		return CommandReplayExternalReservation{}, err
+	}
+	return CommandReplayExternalReservation{
+		ReferenceType:           referenceType,
+		ReferenceNo:             referenceNo,
+		PreparedResponsePayload: preparedResponsePayload,
+	}, nil
+}
+
+func validateExternalLeaseTTL(leaseTTL time.Duration) error {
+	if leaseTTL < time.Second || leaseTTL > maxExternalLeaseTTL {
+		return apierror.BadRequest(apierror.CodeValidationFailed, "leaseTTL must be between 1s and 15m")
+	}
+	return nil
+}
+
+func newCommandReplayExecutionToken() (string, string, error) {
+	raw := make([]byte, commandReplayExecutionTokenSize)
+	if _, err := rand.Read(raw); err != nil {
+		return "", "", err
+	}
+	token := base64.RawURLEncoding.EncodeToString(raw)
+	hash := sha256.Sum256(raw)
+	return token, hex.EncodeToString(hash[:]), nil
+}
+
+func commandReplayExecutionTokenHash(token string) (string, error) {
+	raw, err := base64.RawURLEncoding.DecodeString(token)
+	if err != nil || len(raw) != commandReplayExecutionTokenSize {
+		return "", apierror.Conflict(errCodeCommandReplayInProgress, "External command execution lease is invalid or expired")
+	}
+	hash := sha256.Sum256(raw)
+	return hex.EncodeToString(hash[:]), nil
+}
+
+func hasCurrentExternalLease(record *CommandReplayRecord, tokenHash string, at time.Time) bool {
+	return record != nil && record.Status == CommandReplayStatusStarted && record.ExecutionTokenHash != nil &&
+		record.LeaseExpiresAt != nil && at.Before(*record.LeaseExpiresAt) &&
+		subtle.ConstantTimeCompare([]byte(*record.ExecutionTokenHash), []byte(tokenHash)) == 1
+}
+
+func externalLeaseFromRecord(record *CommandReplayRecord, executionToken string, attemptCount int) *CommandReplayExternalLease {
+	return &CommandReplayExternalLease{
+		RecordID: record.ID, ExecutionToken: executionToken,
+		Reservation: CommandReplayExternalReservation{
+			ReferenceType:           *record.ExternalReferenceType,
+			ReferenceNo:             *record.ExternalReferenceNo,
+			PreparedResponsePayload: append(json.RawMessage(nil), record.ResponsePayload...),
+		},
+		AttemptCount: attemptCount,
+	}
+}
+
+func normalizeCommandReplayBeginRequest(req CommandReplayBeginRequest) (*normalizedCommandReplayBeginRequest, error) {
+	namespace, err := normalizeCommandReplayNamespace(req.Namespace)
+	if err != nil {
+		return nil, err
+	}
+	commandScope, err := normalizeRequiredString("commandScope", req.CommandScope, maxCommandScopeLength)
+	if err != nil {
+		return nil, err
+	}
+	idempotencyKey, err := normalizeRequiredString("idempotencyKey", req.IdempotencyKey, maxIdempotencyKeyLength)
+	if err != nil {
+		return nil, err
+	}
+	requestPayload, err := canonicalRawJSONObject(req.RequestPayload, false)
+	if err != nil {
+		return nil, err
+	}
+	requestHash, err := canonicaljson.Hash(requestPayload)
+	if err != nil {
+		return nil, apierror.BadRequest(apierror.CodeValidationFailed, "payload must be a JSON object")
+	}
+	metadata, err := canonicalRawJSONObject(req.Metadata, true)
+	if err != nil {
+		return nil, err
+	}
+	principalType, err := normalizeOptionalString("principalType", req.PrincipalType, maxPrincipalTypeLength)
+	if err != nil {
+		return nil, err
+	}
+	principalRef, err := normalizeOptionalString("principalRef", req.PrincipalRef, maxPrincipalRefLength)
+	if err != nil {
+		return nil, err
+	}
+	if (principalType == nil) != (principalRef == nil) {
+		return nil, apierror.BadRequest(apierror.CodeValidationFailed, "principalType and principalRef must be provided together")
+	}
+	ttl := req.TTL
+	if ttl <= 0 {
+		ttl = defaultCommandReplayTTL
+	}
+	return &normalizedCommandReplayBeginRequest{
+		namespace:      namespace,
+		commandScope:   commandScope,
+		idempotencyKey: idempotencyKey,
+		requestHash:    requestHash,
+		principalType:  principalType,
+		principalRef:   principalRef,
+		metadata:       metadata,
+		ttl:            ttl,
+	}, nil
+}
+
+func normalizeCommandReplayNamespace(value string) (string, error) {
+	namespace := strings.TrimSpace(value)
+	if utf8.RuneCountInString(namespace) > maxNamespaceLength || !commandReplayNamespacePattern.MatchString(namespace) {
+		return "", apierror.BadRequest(apierror.CodeValidationFailed, "namespace must be a valid dotted command namespace")
+	}
+	return namespace, nil
+}
+
+func normalizeCommandReplayCommandResult(result *CommandReplayCommandResult) (*normalizedCommandReplayCommandResult, error) {
+	if result == nil {
+		return nil, apierror.Internal("Command replay result is required")
+	}
+
+	switch result.Status {
+	case CommandReplayStatusSucceeded:
+		responsePayload, err := canonicalRawJSONObject(result.ResponsePayload, false)
+		if err != nil {
+			return nil, err
+		}
+		if strings.TrimSpace(result.ErrorCode) != "" {
+			return nil, apierror.Internal("Successful command replay result cannot include errorCode")
+		}
+		if result.ReturnError != nil {
+			return nil, apierror.Internal("Successful command replay result cannot include returnError")
+		}
+		return &normalizedCommandReplayCommandResult{
+			status:          result.Status,
+			responsePayload: responsePayload,
+		}, nil
+	case CommandReplayStatusFailed:
+		var apiErr *apierror.APIError
+		if !errors.As(result.ReturnError, &apiErr) || apiErr == nil {
+			return nil, apierror.Internal("Failed command replay result requires APIError returnError")
+		}
+		errorCode, codeErr := normalizeRequiredString("errorCode", apiErr.Detail.Code, maxErrorCodeLength)
+		if codeErr != nil {
+			return nil, codeErr
+		}
+		if providedErrorCode := strings.TrimSpace(result.ErrorCode); providedErrorCode != "" && providedErrorCode != errorCode {
+			return nil, apierror.Internal("Failed command replay result errorCode must match returnError")
+		}
+		if apiErr.Status < 400 || apiErr.Status > 599 {
+			return nil, apierror.Internal("Failed command replay result has invalid error status")
+		}
+		responsePayload, payloadErr := canonicalAPIErrorPayload(apiErr)
+		if payloadErr != nil {
+			return nil, payloadErr
+		}
+		return &normalizedCommandReplayCommandResult{
+			status:          result.Status,
+			responsePayload: responsePayload,
+			errorCode:       errorCode,
+			errorStatus:     apiErr.Status,
+			returnError:     apiErr,
+		}, nil
+	default:
+		return nil, apierror.Internal("Command replay result has invalid status")
+	}
+}
+
+func classifyCommandReplayRecord(record *CommandReplayRecord, requestHash string, now time.Time) (*CommandReplayExecuteResult, error) {
+	if !record.MatchesRequestHash(requestHash) {
+		return nil, apierror.Conflict(errCodeCommandReplayConflict, "Idempotency key was reused with a different request payload")
+	}
+	if record.IsExpiredAt(now) {
+		return nil, apierror.Conflict(errCodeCommandReplayExpired, "Idempotency key has expired")
+	}
+	if record.Status.IsTerminal() {
+		return &CommandReplayExecuteResult{
+			Record:          record,
+			Replayed:        true,
+			ResponsePayload: defaultRawJSONObject(record.ResponsePayload),
+			ErrorCode:       cloneStringPtr(record.ErrorCode),
+			ErrorStatus:     cloneIntPtr(record.ErrorStatus),
+			Status:          record.Status,
+		}, nil
+	}
+	if record.Status == CommandReplayStatusStarted {
+		return nil, apierror.Conflict(errCodeCommandReplayInProgress, "Command replay is already in progress")
+	}
+	return nil, apierror.Internal("Command replay record has invalid status")
+}
+
+func canonicalRawJSONObject(raw json.RawMessage, allowEmpty bool) (json.RawMessage, error) {
+	trimmed := bytes.TrimSpace(raw)
+	if len(trimmed) == 0 {
+		if allowEmpty {
+			return json.RawMessage(`{}`), nil
+		}
+		return nil, apierror.BadRequest(apierror.CodeValidationFailed, "payload must be a JSON object")
+	}
+	if trimmed[0] != '{' {
+		return nil, apierror.BadRequest(apierror.CodeValidationFailed, "payload must be a JSON object")
+	}
+	canonical, err := canonicaljson.Canonicalize(trimmed)
+	if err != nil {
+		return nil, apierror.BadRequest(apierror.CodeValidationFailed, "payload must be a JSON object")
+	}
+	return canonical, nil
+}
+
+func defaultRawJSONObject(raw json.RawMessage) json.RawMessage {
+	if len(bytes.TrimSpace(raw)) == 0 {
+		return json.RawMessage(`{}`)
+	}
+	return append(json.RawMessage(nil), raw...)
+}
+
+func canonicalAPIErrorPayload(apiErr *apierror.APIError) (json.RawMessage, error) {
+	raw, err := json.Marshal(apiErr.ToResponse())
+	if err != nil {
+		return nil, apierror.Internal("Failed to marshal command replay error response")
+	}
+	return canonicalRawJSONObject(raw, false)
+}
+
+func commandReplayBusinessErrorFromRecord(record *CommandReplayRecord) (*apierror.APIError, error) {
+	if record == nil || record.Status != CommandReplayStatusFailed {
+		return nil, nil
+	}
+	if record.ErrorCode == nil || strings.TrimSpace(*record.ErrorCode) == "" || record.ErrorStatus == nil {
+		return nil, apierror.Internal("Failed command replay record is missing error fields")
+	}
+	if *record.ErrorStatus < 400 || *record.ErrorStatus > 599 {
+		return nil, apierror.Internal("Failed command replay record has invalid error status")
+	}
+	var response apierror.ErrorResponse
+	if err := json.Unmarshal(defaultRawJSONObject(record.ResponsePayload), &response); err != nil {
+		return nil, apierror.Internal("Failed command replay record has invalid error response")
+	}
+	if response.Error.Code != strings.TrimSpace(*record.ErrorCode) {
+		return nil, apierror.Internal("Failed command replay record error response does not match errorCode")
+	}
+	if response.Error.Type == "" || response.Error.Message == "" {
+		return nil, apierror.Internal("Failed command replay record error response is incomplete")
+	}
+	return &apierror.APIError{
+		Status: *record.ErrorStatus,
+		Detail: response.Error,
+	}, nil
+}
+
+func normalizeRequiredString(fieldName, value string, maxLength int) (string, error) {
+	normalized := strings.TrimSpace(value)
+	if normalized == "" {
+		return "", apierror.BadRequest(apierror.CodeValidationFailed, fieldName+" is required")
+	}
+	if utf8.RuneCountInString(normalized) > maxLength {
+		return "", apierror.BadRequest(apierror.CodeValidationFailed, fieldName+" is too long")
+	}
+	return normalized, nil
+}
+
+func normalizeOptionalString(fieldName string, value *string, maxLength int) (*string, error) {
+	if value == nil {
+		return nil, nil
+	}
+	normalized := strings.TrimSpace(*value)
+	if normalized == "" {
+		return nil, apierror.BadRequest(apierror.CodeValidationFailed, fieldName+" must not be blank")
+	}
+	if utf8.RuneCountInString(normalized) > maxLength {
+		return nil, apierror.BadRequest(apierror.CodeValidationFailed, fieldName+" is too long")
+	}
+	return &normalized, nil
+}
+
+func (s *CommandReplayService) markSucceeded(ctx context.Context, recordID int64, responsePayload json.RawMessage, completedAt time.Time) error {
+	if markErr := s.repo.MarkSucceeded(ctx, recordID, responsePayload, completedAt); markErr != nil {
+		return apierror.Internal("Failed to mark command replay record as succeeded")
+	}
+	return nil
+}
+
+func (s *CommandReplayService) markFailed(ctx context.Context, recordID int64, errorCode string, errorStatus int, responsePayload json.RawMessage, completedAt time.Time) error {
+	if markErr := s.repo.MarkFailed(ctx, recordID, errorCode, errorStatus, responsePayload, completedAt); markErr != nil {
+		return apierror.Internal("Failed to mark command replay record as failed")
+	}
+	return nil
+}
+
+func isCommandReplayDuplicateCreateError(err error) bool {
+	return errors.Is(err, ErrCommandReplayRecordExists) || database.IsDuplicateKeyError(err)
+}
+
+func (s *CommandReplayService) withTransaction(ctx context.Context, fn func(context.Context) error) error {
+	if s.txManager == nil {
+		return apierror.Internal("Transaction manager is required")
+	}
+	return s.txManager.WithTransaction(ctx, fn)
+}
+
+func cloneStringPtr(value *string) *string {
+	if value == nil {
+		return nil
+	}
+	cloned := *value
+	return &cloned
+}
+
+func cloneTimePtr(value *time.Time) *time.Time {
+	if value == nil {
+		return nil
+	}
+	cloned := *value
+	return &cloned
+}
+
+func cloneIntPtr(value *int) *int {
+	if value == nil {
+		return nil
+	}
+	cloned := *value
+	return &cloned
+}