@stackonward/cli 1.4.0 → 1.5.0

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

@@ -46,7 +46,7 @@ func TestCommandReplayExecuteStandaloneCommitsBusinessFailure(t *testing.T) {
 		t.Fatalf("Execute() result = %#v, want failed result", result)
 	}
 
-	stored, err := repo.FindByScope(ctx, "test.command.replay", "quote:123", "key-123")
+	stored, err := repo.FindByScope(ctx, "test.command.replay", "identity", "user_123", "quote:123", "key-123")
 	if err != nil {
 		t.Fatalf("FindByScope() error = %v", err)
 	}
@@ -101,7 +101,7 @@ func TestCommandReplayExecuteStandaloneRollsBackInfrastructureError(t *testing.T
 		t.Fatalf("Execute() error = %v, want infraErr", err)
 	}
 
-	stored, err := repo.FindByScope(ctx, "test.command.replay", "quote:123", "key-123")
+	stored, err := repo.FindByScope(ctx, "test.command.replay", "identity", "user_123", "quote:123", "key-123")
 	if err != nil {
 		t.Fatalf("FindByScope() error = %v", err)
 	}
@@ -147,7 +147,7 @@ func TestCommandReplayExecuteJoinsOuterTransactionRollback(t *testing.T) {
 		t.Fatalf("WithTransaction() error = %v, want rollbackErr", err)
 	}
 
-	stored, err := repo.FindByScope(ctx, "test.command.replay", "quote:123", "key-123")
+	stored, err := repo.FindByScope(ctx, "test.command.replay", "identity", "user_123", "quote:123", "key-123")
 	if err != nil {
 		t.Fatalf("FindByScope() error = %v", err)
 	}
@@ -214,7 +214,7 @@ func TestCommandReplayExecuteRejectsConcurrentDuplicateOnPostgres(t *testing.T)
 		t.Fatalf("business executions = %d, want 1", executions.Load())
 	}
 
-	stored, err := repo.FindByScope(ctx, "test.command.replay", "quote:123", "key-123")
+	stored, err := repo.FindByScope(ctx, "test.command.replay", "identity", "user_123", "quote:123", "key-123")
 	if err != nil {
 		t.Fatalf("FindByScope() error = %v", err)
 	}
@@ -223,6 +223,89 @@ func TestCommandReplayExecuteRejectsConcurrentDuplicateOnPostgres(t *testing.T)
 	}
 }
 
+func TestCommandReplayExecuteAllowsConcurrentSameKeyForDifferentPrincipalsOnPostgres(t *testing.T) {
+	db := openPersistentCommandReplayPostgres(t)
+	repo := commandreplay.NewCommandReplayRepository(db)
+	service := commandreplay.NewCommandReplayService(repo, database.NewTransactionManager(db))
+	ctx := context.Background()
+	firstStarted := make(chan struct{})
+	releaseFirst := make(chan struct{})
+	firstDone := make(chan error, 1)
+	secondDone := make(chan error, 1)
+	releasedFirst := false
+	defer func() {
+		if !releasedFirst {
+			close(releaseFirst)
+		}
+	}()
+	var executions atomic.Int32
+
+	go func() {
+		_, err := service.Execute(ctx, persistentCommandReplayRequest(json.RawMessage(`{"amount":100}`)), func(context.Context, *commandreplay.CommandReplayRecord) (*commandreplay.CommandReplayCommandResult, error) {
+			executions.Add(1)
+			close(firstStarted)
+			<-releaseFirst
+			return &commandreplay.CommandReplayCommandResult{
+				Status:          commandreplay.CommandReplayStatusSucceeded,
+				ResponsePayload: json.RawMessage(`{"status":"first"}`),
+			}, nil
+		})
+		firstDone <- err
+	}()
+
+	select {
+	case <-firstStarted:
+	case <-time.After(5 * time.Second):
+		t.Fatal("first principal did not enter its transaction")
+	}
+
+	secondRequest := persistentCommandReplayRequest(json.RawMessage(`{"amount":100}`))
+	secondRequest.PrincipalRef = "user_456"
+	go func() {
+		_, err := service.Execute(ctx, secondRequest, func(context.Context, *commandreplay.CommandReplayRecord) (*commandreplay.CommandReplayCommandResult, error) {
+			executions.Add(1)
+			return &commandreplay.CommandReplayCommandResult{
+				Status:          commandreplay.CommandReplayStatusSucceeded,
+				ResponsePayload: json.RawMessage(`{"status":"second"}`),
+			}, nil
+		})
+		secondDone <- err
+	}()
+
+	select {
+	case err := <-secondDone:
+		if err != nil {
+			t.Fatalf("second principal Execute() error = %v", err)
+		}
+	case <-time.After(5 * time.Second):
+		t.Fatal("second principal was blocked by another principal's scope lock")
+	}
+	close(releaseFirst)
+	releasedFirst = true
+
+	select {
+	case err := <-firstDone:
+		if err != nil {
+			t.Fatalf("first principal Execute() error = %v", err)
+		}
+	case <-time.After(5 * time.Second):
+		t.Fatal("first principal did not complete")
+	}
+	if executions.Load() != 2 {
+		t.Fatalf("business executions = %d, want 2", executions.Load())
+	}
+
+	for _, principalRef := range []string{"user_123", "user_456"} {
+		stored, err := repo.FindByScope(ctx, "test.command.replay", "identity", principalRef, "quote:123", "key-123")
+		if err != nil {
+			t.Fatalf("FindByScope(%s) error = %v", principalRef, err)
+		}
+		if stored == nil || stored.Status != commandreplay.CommandReplayStatusSucceeded {
+			t.Fatalf("stored record for %s = %#v, want succeeded", principalRef, stored)
+		}
+	}
+}
+
 func newPersistentCommandReplayService(t *testing.T) (*commandreplay.CommandReplayService, commandreplay.CommandReplayRepository) {
 	t.Helper()
 	service, repo, _, _ := newPersistentCommandReplayFixture(t)
@@ -248,13 +331,15 @@ type sqliteCommandReplayRepository struct {
 	commandreplay.CommandReplayRepository
 }
 
-func (r sqliteCommandReplayRepository) TryAcquireScopeLock(ctx context.Context, namespace, commandScope, idempotencyKey string) (bool, error) {
+func (r sqliteCommandReplayRepository) TryAcquireScopeLock(ctx context.Context, namespace, principalType, principalRef, commandScope, idempotencyKey string) (bool, error) {
 	return true, nil
 }
 
 func persistentCommandReplayRequest(payload json.RawMessage) commandreplay.CommandReplayBeginRequest {
 	return commandreplay.CommandReplayBeginRequest{
 		Namespace:      "test.command.replay",
+		PrincipalType:  "identity",
+		PrincipalRef:   "user_123",
 		CommandScope:   "quote:123",
 		IdempotencyKey: "key-123",
 		RequestPayload: payload,
@@ -275,8 +360,8 @@ func createPersistentCommandReplayRecordSchema(t *testing.T, db *gorm.DB) {
 			command_scope TEXT NOT NULL,
 			idempotency_key TEXT NOT NULL,
 			request_hash TEXT NOT NULL,
-			principal_type TEXT,
-			principal_ref TEXT,
+			principal_type TEXT NOT NULL,
+			principal_ref TEXT NOT NULL,
 			status TEXT NOT NULL DEFAULT 'started',
 			response_payload TEXT NOT NULL DEFAULT '{}',
 			error_code TEXT,
@@ -296,8 +381,8 @@ func createPersistentCommandReplayRecordSchema(t *testing.T, db *gorm.DB) {
 		t.Fatalf("create command replay schema: %v", err)
 	}
 	if err := db.Exec(`
-		CREATE UNIQUE INDEX uk_sys_command_replay_records_namespace_scope_key
-		ON sys_command_replay_records (namespace, command_scope, idempotency_key)
+		CREATE UNIQUE INDEX uk_sys_command_replay_records_principal_scope_key
+		ON sys_command_replay_records (namespace, principal_type, principal_ref, command_scope, idempotency_key)
 	`).Error; err != nil {
 		t.Fatalf("create command replay unique index: %v", err)
 	}
@@ -381,8 +466,8 @@ func createPersistentCommandReplayPostgresSchema(t *testing.T, db *gorm.DB) {
 			command_scope VARCHAR(128) NOT NULL,
 			idempotency_key VARCHAR(191) NOT NULL,
 			request_hash CHAR(64) NOT NULL,
-			principal_type VARCHAR(32),
-			principal_ref VARCHAR(64),
+			principal_type VARCHAR(32) NOT NULL,
+			principal_ref VARCHAR(64) NOT NULL,
 			status VARCHAR(20) NOT NULL DEFAULT 'started',
 			response_payload JSONB NOT NULL DEFAULT '{}'::jsonb,
 			error_code VARCHAR(120),
@@ -397,8 +482,8 @@ func createPersistentCommandReplayPostgresSchema(t *testing.T, db *gorm.DB) {
 			external_attempt_count INTEGER NOT NULL DEFAULT 0,
 			external_last_error_code VARCHAR(120),
 			metadata JSONB NOT NULL DEFAULT '{}'::jsonb,
-			CONSTRAINT uk_sys_command_replay_records_namespace_scope_key
-				UNIQUE (namespace, command_scope, idempotency_key)
+			CONSTRAINT uk_sys_command_replay_records_principal_scope_key
+				UNIQUE (namespace, principal_type, principal_ref, command_scope, idempotency_key)
 		)
 	`).Error; err != nil {
 		t.Fatalf("create PostgreSQL command replay schema: %v", err)

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

@@ -18,14 +18,16 @@ import (
 	"{{module}}/pkg/apierror"
 )
 
-const commandReplayTestNamespace = "test.command.replay"
+const (
+	commandReplayTestNamespace     = "test.command.replay"
+	commandReplayTestPrincipalType = "identity"
+	commandReplayTestPrincipalRef  = "user_123"
+)
 
 var commandReplayTestNow = time.Date(2026, 5, 28, 10, 0, 0, 0, time.UTC)
 
 func TestCommandReplayExecuteSucceeds(t *testing.T) {
 	service, repo := newTestCommandReplayService(t)
-	principalType := "identity"
-	principalRef := "user_123"
 	fnCalled := 0
 
 	result, err := service.Execute(context.Background(), CommandReplayBeginRequest{
@@ -33,8 +35,8 @@ func TestCommandReplayExecuteSucceeds(t *testing.T) {
 		CommandScope:   " quote:123 ",
 		IdempotencyKey: " key-123 ",
 		RequestPayload: json.RawMessage(`{"currency":"USD","amount":100}`),
-		PrincipalType:  &principalType,
-		PrincipalRef:   &principalRef,
+		PrincipalType:  " identity ",
+		PrincipalRef:   " user_123 ",
 	}, func(ctx context.Context, record *CommandReplayRecord) (*CommandReplayCommandResult, error) {
 		fnCalled++
 		if record.ID == 0 {
@@ -61,7 +63,7 @@ func TestCommandReplayExecuteSucceeds(t *testing.T) {
 		t.Fatalf("Execute() ResponsePayload = %s, want canonical object", result.ResponsePayload)
 	}
 
-	stored := repo.mustFind(t, commandReplayTestNamespace, "quote:123", "key-123")
+	stored := repo.mustFind(t, commandReplayTestNamespace, commandReplayTestPrincipalType, commandReplayTestPrincipalRef, "quote:123", "key-123")
 	if stored.Status != CommandReplayStatusSucceeded {
 		t.Fatalf("stored Status = %q, want succeeded", stored.Status)
 	}
@@ -77,11 +79,11 @@ func TestCommandReplayExecuteSucceeds(t *testing.T) {
 	if stored.CompletedAt == nil || !stored.CompletedAt.Equal(commandReplayTestNow) {
 		t.Fatalf("stored CompletedAt = %v, want %s", stored.CompletedAt, commandReplayTestNow)
 	}
-	if stored.PrincipalType == nil || *stored.PrincipalType != principalType {
-		t.Fatalf("stored PrincipalType = %v, want %q", stored.PrincipalType, principalType)
+	if stored.PrincipalType != commandReplayTestPrincipalType {
+		t.Fatalf("stored PrincipalType = %q, want %q", stored.PrincipalType, commandReplayTestPrincipalType)
 	}
-	if stored.PrincipalRef == nil || *stored.PrincipalRef != principalRef {
-		t.Fatalf("stored PrincipalRef = %v, want %q", stored.PrincipalRef, principalRef)
+	if stored.PrincipalRef != commandReplayTestPrincipalRef {
+		t.Fatalf("stored PrincipalRef = %q, want %q", stored.PrincipalRef, commandReplayTestPrincipalRef)
 	}
 }
 
@@ -140,6 +142,29 @@ func TestCommandReplayExecuteRejectsHashConflict(t *testing.T) {
 	assertAPIError(t, err, http.StatusConflict, errCodeCommandReplayConflict)
 }
 
+func TestCommandReplayExecuteIsolatesSameKeyByPrincipal(t *testing.T) {
+	service, repo := newTestCommandReplayService(t)
+	first := beginRequest(json.RawMessage(`{"amount":100}`))
+	second := beginRequest(json.RawMessage(`{"amount":100}`))
+	second.PrincipalRef = "user_456"
+
+	firstResult, err := service.Execute(context.Background(), first, successCommandReplayFunc(t))
+	if err != nil {
+		t.Fatalf("Execute(first) error = %v", err)
+	}
+	secondResult, err := service.Execute(context.Background(), second, successCommandReplayFunc(t))
+	if err != nil {
+		t.Fatalf("Execute(second) error = %v", err)
+	}
+	if firstResult.Replayed || secondResult.Replayed {
+		t.Fatalf("new principal-scoped commands must not replay: first=%v second=%v", firstResult.Replayed, secondResult.Replayed)
+	}
+	if repo.mustFind(t, commandReplayTestNamespace, commandReplayTestPrincipalType, commandReplayTestPrincipalRef, "quote:123", "key-123").RequestHash !=
+		repo.mustFind(t, commandReplayTestNamespace, commandReplayTestPrincipalType, "user_456", "quote:123", "key-123").RequestHash {
+		t.Fatal("principal unexpectedly changed the payload-only request fingerprint")
+	}
+}
+
 func TestCommandReplayExecuteRejectsExpiredRecord(t *testing.T) {
 	service, repo := newTestCommandReplayService(t)
 	repo.seed(seedCommandReplayRecord(t, json.RawMessage(`{"amount":100}`), func(record *CommandReplayRecord) {
@@ -169,7 +194,7 @@ func TestCommandReplayExecuteBusinessFailureCommitsAndReturnsBusinessError(t *te
 		t.Fatalf("Execute() result = %#v, want failed result", result)
 	}
 
-	stored := repo.mustFind(t, commandReplayTestNamespace, "quote:123", "key-123")
+	stored := repo.mustFind(t, commandReplayTestNamespace, commandReplayTestPrincipalType, commandReplayTestPrincipalRef, "quote:123", "key-123")
 	if stored.Status != CommandReplayStatusFailed {
 		t.Fatalf("stored Status = %q, want failed", stored.Status)
 	}
@@ -198,7 +223,7 @@ func TestCommandReplayExecuteInfrastructureErrorDoesNotMarkTerminal(t *testing.T
 		t.Fatalf("Execute() error = %v, want infraErr", err)
 	}
 
-	stored := repo.mustFind(t, commandReplayTestNamespace, "quote:123", "key-123")
+	stored := repo.mustFind(t, commandReplayTestNamespace, commandReplayTestPrincipalType, commandReplayTestPrincipalRef, "quote:123", "key-123")
 	if stored.Status.IsTerminal() {
 		t.Fatalf("stored Status = %q, want non-terminal", stored.Status)
 	}
@@ -258,19 +283,17 @@ func TestCommandReplayExecuteRejectsInvalidNamespace(t *testing.T) {
 	assertAPIError(t, err, http.StatusBadRequest, apierror.CodeValidationFailed)
 }
 
-func TestCommandReplayExecuteRejectsIncompletePrincipal(t *testing.T) {
-	principalType := "identity"
-	principalRef := "ipr_123"
-	blank := " \t "
+func TestCommandReplayExecuteRejectsInvalidPrincipal(t *testing.T) {
 	tests := []struct {
 		name          string
-		principalType *string
-		principalRef  *string
+		principalType string
+		principalRef  string
 	}{
-		{name: "missing principal ref", principalType: &principalType},
-		{name: "missing principal type", principalRef: &principalRef},
-		{name: "blank principal pair", principalType: &blank, principalRef: &blank},
-		{name: "blank principal ref", principalType: &principalType, principalRef: &blank},
+		{name: "missing principal ref", principalType: commandReplayTestPrincipalType},
+		{name: "missing principal type", principalRef: commandReplayTestPrincipalRef},
+		{name: "blank principal pair", principalType: " \t ", principalRef: " \t "},
+		{name: "overlong principal type", principalType: strings.Repeat("a", maxPrincipalTypeLength+1), principalRef: commandReplayTestPrincipalRef},
+		{name: "overlong principal ref", principalType: commandReplayTestPrincipalType, principalRef: strings.Repeat("a", maxPrincipalRefLength+1)},
 	}
 
 	for _, tt := range tests {
@@ -372,7 +395,7 @@ func TestCommandReplayExternalLifecycle(t *testing.T) {
 	if lease.ExecutionToken == "" || lease.AttemptCount != 1 || lease.Reservation.ReferenceNo != "cpo_1" {
 		t.Fatalf("lease = %#v", lease)
 	}
-	stored := repo.mustFind(t, commandReplayTestNamespace, "quote:123", "key-123")
+	stored := repo.mustFind(t, commandReplayTestNamespace, commandReplayTestPrincipalType, commandReplayTestPrincipalRef, "quote:123", "key-123")
 	if !stored.HasExternalReservation() || stored.ExecutionTokenHash == nil || stored.ExternalAttemptCount != 1 {
 		t.Fatalf("stored external record = %#v", stored)
 	}
@@ -389,7 +412,7 @@ func TestCommandReplayExternalLifecycle(t *testing.T) {
 	if err != nil || result.Status != CommandReplayStatusSucceeded {
 		t.Fatalf("CompleteExternal() = %#v, %v", result, err)
 	}
-	stored = repo.mustFind(t, commandReplayTestNamespace, "quote:123", "key-123")
+	stored = repo.mustFind(t, commandReplayTestNamespace, commandReplayTestPrincipalType, commandReplayTestPrincipalRef, "quote:123", "key-123")
 	if stored.HasExternalReservation() || stored.ExecutionTokenHash != nil || stored.Status != CommandReplayStatusSucceeded {
 		t.Fatalf("completed stored record = %#v", stored)
 	}
@@ -453,7 +476,7 @@ func TestCommandReplayExternalDeferAndRecoveryClaim(t *testing.T) {
 	if err := service.DeferExternal(context.Background(), lease.RecordID, lease.ExecutionToken, "provider_timeout", nextRecoveryAt); err != nil {
 		t.Fatalf("DeferExternal() error = %v", err)
 	}
-	stored := repo.mustFind(t, commandReplayTestNamespace, "quote:123", "key-123")
+	stored := repo.mustFind(t, commandReplayTestNamespace, commandReplayTestPrincipalType, commandReplayTestPrincipalRef, "quote:123", "key-123")
 	if stored.ExecutionTokenHash != nil || stored.ExternalLastErrorCode == nil || *stored.ExternalLastErrorCode != "provider_timeout" {
 		t.Fatalf("deferred record = %#v", stored)
 	}
@@ -586,6 +609,8 @@ func newTestCommandReplayService(t *testing.T) (*CommandReplayService, *fakeComm
 func beginRequest(payload json.RawMessage) CommandReplayBeginRequest {
 	return CommandReplayBeginRequest{
 		Namespace:      commandReplayTestNamespace,
+		PrincipalType:  commandReplayTestPrincipalType,
+		PrincipalRef:   commandReplayTestPrincipalRef,
 		CommandScope:   "quote:123",
 		IdempotencyKey: "key-123",
 		RequestPayload: payload,
@@ -599,6 +624,8 @@ func seedCommandReplayRecord(t *testing.T, payload json.RawMessage, mutate func(
 
 	record := &CommandReplayRecord{
 		Namespace:       commandReplayTestNamespace,
+		PrincipalType:   commandReplayTestPrincipalType,
+		PrincipalRef:    commandReplayTestPrincipalRef,
 		CommandScope:    "quote:123",
 		IdempotencyKey:  "key-123",
 		RequestHash:     mustCanonicalHash(t, payload),
@@ -669,18 +696,18 @@ func newFakeCommandReplayRepository() *fakeCommandReplayRepository {
 	}
 }
 
-func (r *fakeCommandReplayRepository) TryAcquireScopeLock(ctx context.Context, namespace, commandScope, idempotencyKey string) (bool, error) {
+func (r *fakeCommandReplayRepository) TryAcquireScopeLock(ctx context.Context, namespace, principalType, principalRef, commandScope, idempotencyKey string) (bool, error) {
 	r.mu.Lock()
 	defer r.mu.Unlock()
 
 	return r.lockAcquired, nil
 }
 
-func (r *fakeCommandReplayRepository) FindByScope(ctx context.Context, namespace, commandScope, idempotencyKey string) (*CommandReplayRecord, error) {
+func (r *fakeCommandReplayRepository) FindByScope(ctx context.Context, namespace, principalType, principalRef, commandScope, idempotencyKey string) (*CommandReplayRecord, error) {
 	r.mu.Lock()
 	defer r.mu.Unlock()
 
-	record := r.records[commandReplayRecordKey(namespace, commandScope, idempotencyKey)]
+	record := r.records[commandReplayRecordKey(namespace, principalType, principalRef, commandScope, idempotencyKey)]
 	return cloneCommandReplayRecord(record), nil
 }
 
@@ -692,7 +719,7 @@ func (r *fakeCommandReplayRepository) Create(ctx context.Context, record *Comman
 	r.mu.Lock()
 	defer r.mu.Unlock()
 
-	key := commandReplayRecordKey(record.Namespace, record.CommandScope, record.IdempotencyKey)
+	key := commandReplayRecordKey(record.Namespace, record.PrincipalType, record.PrincipalRef, record.CommandScope, record.IdempotencyKey)
 	if _, exists := r.records[key]; exists {
 		return ErrCommandReplayRecordExists
 	}
@@ -835,17 +862,17 @@ func (r *fakeCommandReplayRepository) seed(record *CommandReplayRecord) {
 		r.nextID++
 	}
 	record.ID = stored.ID
-	key := commandReplayRecordKey(stored.Namespace, stored.CommandScope, stored.IdempotencyKey)
+	key := commandReplayRecordKey(stored.Namespace, stored.PrincipalType, stored.PrincipalRef, stored.CommandScope, stored.IdempotencyKey)
 	r.records[key] = stored
 }
 
-func (r *fakeCommandReplayRepository) mustFind(t *testing.T, namespace, commandScope, idempotencyKey string) *CommandReplayRecord {
+func (r *fakeCommandReplayRepository) mustFind(t *testing.T, namespace, principalType, principalRef, commandScope, idempotencyKey string) *CommandReplayRecord {
 	t.Helper()
 
 	r.mu.Lock()
 	defer r.mu.Unlock()
 
-	record := r.records[commandReplayRecordKey(namespace, commandScope, idempotencyKey)]
+	record := r.records[commandReplayRecordKey(namespace, principalType, principalRef, commandScope, idempotencyKey)]
 	if record == nil {
 		t.Fatalf("record not found")
 	}
@@ -861,8 +888,8 @@ func (r *fakeCommandReplayRepository) findByIDLocked(id int64) *CommandReplayRec
 	return nil
 }
 
-func commandReplayRecordKey(namespace, commandScope, idempotencyKey string) string {
-	return namespace + "\x00" + commandScope + "\x00" + idempotencyKey
+func commandReplayRecordKey(namespace, principalType, principalRef, commandScope, idempotencyKey string) string {
+	return namespace + "\x00" + principalType + "\x00" + principalRef + "\x00" + commandScope + "\x00" + idempotencyKey
 }
 
 func cloneCommandReplayRecord(record *CommandReplayRecord) *CommandReplayRecord {
@@ -870,8 +897,6 @@ func cloneCommandReplayRecord(record *CommandReplayRecord) *CommandReplayRecord
 		return nil
 	}
 	cloned := *record
-	cloned.PrincipalType = cloneStringPtr(record.PrincipalType)
-	cloned.PrincipalRef = cloneStringPtr(record.PrincipalRef)
 	cloned.ErrorCode = cloneStringPtr(record.ErrorCode)
 	cloned.ErrorStatus = cloneIntPtr(record.ErrorStatus)
 	cloned.ResponsePayload = append(json.RawMessage(nil), record.ResponsePayload...)

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

@@ -18,10 +18,10 @@ type CommandReplayBeginRequest struct {
 	IdempotencyKey string
 	// RequestPayload 命令请求的规范 JSON 对象载荷。
 	RequestPayload json.RawMessage
-	// PrincipalType 请求主体类型。
-	PrincipalType *string
-	// PrincipalRef 请求主体公开引用。
-	PrincipalRef *string
+	// PrincipalType 是参与幂等作用域的可信调用主体类型。
+	PrincipalType string
+	// PrincipalRef 是参与幂等作用域的可信调用主体公开引用。
+	PrincipalRef string
 	// Metadata 扩展元数据 JSON 对象。
 	Metadata json.RawMessage
 	// TTL 幂等记录保留时长。
@@ -106,8 +106,8 @@ type normalizedCommandReplayBeginRequest struct {
 	commandScope   string
 	idempotencyKey string
 	requestHash    string
-	principalType  *string
-	principalRef   *string
+	principalType  string
+	principalRef   string
 	metadata       json.RawMessage
 	ttl            time.Duration
 }

package/dist/resources/templates/go-backend/internal/core/integrationevent/config.go

@@ -0,0 +1,24 @@
+package integrationevent
+
+import (
+	"fmt"
+	"strings"
+)
+
+const maxSubscriberCodeLength = 64
+
+// ReceiverConfig 定义单个入站事件接收方的稳定订阅者身份。
+type ReceiverConfig struct {
+	SubscriberCode string
+}
+
+func (c ReceiverConfig) normalized() (ReceiverConfig, error) {
+	c.SubscriberCode = strings.TrimSpace(c.SubscriberCode)
+	if c.SubscriberCode == "" {
+		return ReceiverConfig{}, fmt.Errorf("integration event subscriber code is required")
+	}
+	if len(c.SubscriberCode) > maxSubscriberCodeLength {
+		return ReceiverConfig{}, fmt.Errorf("integration event subscriber code exceeds %d bytes", maxSubscriberCodeLength)
+	}
+	return c, nil
+}

package/dist/resources/templates/go-backend/internal/core/integrationevent/errors.go

@@ -0,0 +1,53 @@
+package integrationevent
+
+import (
+	"errors"
+	"fmt"
+)
+
+var (
+	// ErrEnvelopeInvalid 表示接收方提交的已验证信封不满足核心持久化合同。
+	ErrEnvelopeInvalid = errors.New("integration event envelope is invalid")
+	// ErrHandlerNotRegistered 表示没有消费者为精确 source/type/schema 注册处理器。
+	ErrHandlerNotRegistered = errors.New("integration event handler is not registered")
+	// ErrIdentityConflict 表示同一全局事件身份绑定了不同规范信封。
+	ErrIdentityConflict = errors.New("integration event identity conflicts with the persisted envelope")
+	// ErrVersionConflict 表示事件版本不高于水位且无法证明是已处理事件。
+	ErrVersionConflict = errors.New("integration event aggregate version conflicts with the checkpoint")
+	// ErrReceiptStateConflict 表示持久回执处于无法安全重放的状态。
+	ErrReceiptStateConflict = errors.New("integration event receipt state conflicts with replay")
+)
+
+// VersionGapError 表示事件版本领先于当前连续水位，调用方应稍后重试同一事件。
+type VersionGapError struct {
+	Expected int64
+	Actual   int64
+}
+
+func (e *VersionGapError) Error() string {
+	return fmt.Sprintf("integration event aggregate version gap: expected %d, got %d", e.Expected, e.Actual)
+}
+
+// Retryable 标识版本缺口可以在前序事件到达后重试。
+func (e *VersionGapError) Retryable() bool { return true }
+
+// HandlerError 表示消费者处理失败，整个入站事务已回滚并可重试。
+type HandlerError struct {
+	Cause error
+}
+
+func (e *HandlerError) Error() string {
+	return fmt.Sprintf("integration event handler failed: %v", e.Cause)
+}
+
+// Unwrap 返回消费者处理器的原始错误。
+func (e *HandlerError) Unwrap() error { return e.Cause }
+
+// Retryable 保留消费者对失败是否可重试的显式分类。
+func (e *HandlerError) Retryable() bool { return IsRetryable(e.Cause) }
+
+// IsRetryable 判断错误是否允许发送方稍后重试同一事件身份。
+func IsRetryable(err error) bool {
+	var retryable interface{ Retryable() bool }
+	return errors.As(err, &retryable) && retryable.Retryable()
+}

package/dist/resources/templates/go-backend/internal/core/integrationevent/model.go

@@ -0,0 +1,71 @@
+package integrationevent
+
+import (
+	"encoding/json"
+	"time"
+)
+
+// ReceiptProcessingStatus 表示订阅者回执的持久处理状态。
+type ReceiptProcessingStatus string
+
+const (
+	ReceiptProcessingStatusProcessing ReceiptProcessingStatus = "processing"
+	ReceiptProcessingStatusProcessed  ReceiptProcessingStatus = "processed"
+	ReceiptProcessingStatusFailed     ReceiptProcessingStatus = "failed"
+)
+
+// InboxRecord 保存全局唯一事件身份及其规范信封。
+type InboxRecord struct {
+	ID               int64           `gorm:"column:id;primaryKey;autoIncrement"`
+	SourceSystem     string          `gorm:"column:source_system;type:varchar(191);not null;uniqueIndex:uk_sys_integration_event_inbox_identity,priority:1"`
+	EventID          string          `gorm:"column:event_id;type:varchar(191);not null;uniqueIndex:uk_sys_integration_event_inbox_identity,priority:2"`
+	EventType        string          `gorm:"column:event_type;type:varchar(191);not null"`
+	SchemaVersion    string          `gorm:"column:schema_version;type:varchar(32);not null"`
+	ProductCode      string          `gorm:"column:product_code;type:varchar(50);not null"`
+	AggregateType    string          `gorm:"column:aggregate_type;type:varchar(128);not null"`
+	AggregateRef     string          `gorm:"column:aggregate_ref;type:varchar(191);not null"`
+	AggregateVersion int64           `gorm:"column:aggregate_version;not null"`
+	PayloadHash      string          `gorm:"column:payload_hash;type:char(64);not null"`
+	EventPayload     json.RawMessage `gorm:"column:event_payload;type:jsonb;not null"`
+	ReceivedAt       time.Time       `gorm:"column:received_at;type:timestamptz(3);not null"`
+	CreatedAt        time.Time       `gorm:"column:created_at;type:timestamptz(3);not null"`
+}
+
+// TableName 指定全局入站事件身份表。
+func (InboxRecord) TableName() string { return "sys_integration_event_inbox" }
+
+// ReceiptRecord 保存单个订阅者对一个全局事件的处理回执。
+type ReceiptRecord struct {
+	ID                  int64                   `gorm:"column:id;primaryKey;autoIncrement"`
+	SourceSystem        string                  `gorm:"column:source_system;type:varchar(191);not null;uniqueIndex:uk_sys_integration_event_receipts_subscriber_event,priority:1"`
+	SubscriberCode      string                  `gorm:"column:subscriber_code;type:varchar(64);not null;uniqueIndex:uk_sys_integration_event_receipts_subscriber_event,priority:2"`
+	EventID             string                  `gorm:"column:event_id;type:varchar(191);not null;uniqueIndex:uk_sys_integration_event_receipts_subscriber_event,priority:3"`
+	Status              ReceiptProcessingStatus `gorm:"column:status;type:varchar(20);not null"`
+	ReceiptStatus       *ReceiptOutcome         `gorm:"column:receipt_status;type:varchar(20)"`
+	ErrorCode           *string                 `gorm:"column:error_code;type:varchar(120)"`
+	ProcessingStartedAt time.Time               `gorm:"column:processing_started_at;type:timestamptz(3);not null"`
+	ProcessedAt         *time.Time              `gorm:"column:processed_at;type:timestamptz(3)"`
+	CreatedAt           time.Time               `gorm:"column:created_at;type:timestamptz(3);not null"`
+	UpdatedAt           time.Time               `gorm:"column:updated_at;type:timestamptz(3);not null"`
+}
+
+// TableName 指定订阅者事件回执表。
+func (ReceiptRecord) TableName() string { return "sys_integration_event_receipts" }
+
+// AggregateCheckpoint 保存单个订阅者对一个上游聚合的最后连续版本。
+type AggregateCheckpoint struct {
+	ID                   int64     `gorm:"column:id;primaryKey;autoIncrement"`
+	SourceSystem         string    `gorm:"column:source_system;type:varchar(191);not null;uniqueIndex:uk_sys_integration_aggregate_checkpoints_scope,priority:1"`
+	SubscriberCode       string    `gorm:"column:subscriber_code;type:varchar(64);not null;uniqueIndex:uk_sys_integration_aggregate_checkpoints_scope,priority:2"`
+	AggregateType        string    `gorm:"column:aggregate_type;type:varchar(128);not null;uniqueIndex:uk_sys_integration_aggregate_checkpoints_scope,priority:3"`
+	AggregateRef         string    `gorm:"column:aggregate_ref;type:varchar(191);not null;uniqueIndex:uk_sys_integration_aggregate_checkpoints_scope,priority:4"`
+	LastAggregateVersion int64     `gorm:"column:last_aggregate_version;not null"`
+	LastEventID          string    `gorm:"column:last_event_id;type:varchar(191);not null"`
+	LastPayloadHash      string    `gorm:"column:last_payload_hash;type:char(64);not null"`
+	RevisionNo           int64     `gorm:"column:revision_no;not null"`
+	CreatedAt            time.Time `gorm:"column:created_at;type:timestamptz(3);not null"`
+	UpdatedAt            time.Time `gorm:"column:updated_at;type:timestamptz(3);not null"`
+}
+
+// TableName 指定订阅者聚合连续水位表。
+func (AggregateCheckpoint) TableName() string { return "sys_integration_aggregate_checkpoints" }