create-wakii-stack 0.0.0-stage → 0.1.1

package/stack-template/services/go-svc/internal/consumer/envelope_test.go

@@ -0,0 +1,154 @@
+package consumer
+
+// envelope_test.go — golden fixtures (contracts/events/fixtures, READ-ONLY)
+// là hợp đồng machine-checkable: consumer PHẢI parse được cả 5 file, KHÔNG
+// tự bịa envelope (context pack sf-3).
+
+import (
+	"encoding/json"
+	"os"
+	"path/filepath"
+	"runtime"
+	"testing"
+	"time"
+
+	"github.com/google/uuid"
+
+	"github.com/wakii-dev/architecture-overview/services/go-svc/internal/model"
+)
+
+// fixturesDir — absolute path contracts/events/fixtures từ package này.
+func fixturesDir(t *testing.T) string {
+	t.Helper()
+	_, thisFile, _, ok := runtime.Caller(0)
+	if !ok {
+		t.Fatal("cannot locate test file")
+	}
+	dir := filepath.Join(filepath.Dir(thisFile), "..", "..", "..", "..", "contracts", "events", "fixtures")
+	if _, err := os.Stat(dir); os.IsNotExist(err) {
+		t.Skip("contracts/events/fixtures không tồn tại cạnh service (standalone copy) — skip golden fixture test")
+	}
+	return dir
+}
+
+func loadFixture(t *testing.T, name string) []byte {
+	t.Helper()
+	raw, err := os.ReadFile(filepath.Join(fixturesDir(t), name))
+	if err != nil {
+		t.Fatalf("read fixture %s: %v", name, err)
+	}
+	return raw
+}
+
+func TestParseEnvelope_AllGoldenFixtures(t *testing.T) {
+	cases := []struct {
+		file string
+		want string
+	}{
+		{"task.created.json", model.ActionTaskCreated},
+		{"task.updated.json", model.ActionTaskUpdated},
+		{"task.assigned.json", model.ActionTaskAssigned},
+		{"task.deleted.json", model.ActionTaskDeleted},
+		{"task.assignment_failed.json", model.ActionTaskAssignmentFailed},
+	}
+	for _, tc := range cases {
+		t.Run(tc.file, func(t *testing.T) {
+			env, err := ParseEnvelope(loadFixture(t, tc.file))
+			if err != nil {
+				t.Fatalf("parse golden fixture %s: %v", tc.file, err)
+			}
+			if env.Type != tc.want {
+				t.Errorf("type = %q, want %q", env.Type, tc.want)
+			}
+			if env.SchemaVersion != 1 {
+				t.Errorf("schemaVersion = %d, want 1", env.SchemaVersion)
+			}
+			if env.ID == uuid.Nil {
+				t.Error("id rỗng — fixtures phải mang envelope id")
+			}
+			if env.OccurredAt.IsZero() {
+				t.Error("occurredAt zero")
+			}
+		})
+	}
+}
+
+// TestParseEnvelope_AssignedFixturePayload — fail hook + activity row dùng
+// đúng assigneeId/userId của fixture (không bịa).
+func TestParseEnvelope_AssignedFixturePayload(t *testing.T) {
+	env, err := ParseEnvelope(loadFixture(t, "task.assigned.json"))
+	if err != nil {
+		t.Fatalf("parse: %v", err)
+	}
+	var p taskUserPayload
+	if err := json.Unmarshal(env.Payload, &p); err != nil {
+		t.Fatalf("decode payload: %v", err)
+	}
+	if p.TaskID.String() != "c7c7c7c7-7777-4777-8777-777777777777" {
+		t.Errorf("taskId = %s", p.TaskID)
+	}
+	if p.UserID.String() != "11111111-1111-4111-8111-111111111111" {
+		t.Errorf("userId = %s (alice fixture)", p.UserID)
+	}
+	if p.AssigneeID.String() != "22222222-2222-4222-8222-222222222222" {
+		t.Errorf("assigneeId = %s (bob fixture — KHÔNG phải svc-fail)", p.AssigneeID)
+	}
+}
+
+func TestParseEnvelope_InvalidMatrix(t *testing.T) {
+	cases := []struct {
+		name string
+		raw  string
+	}{
+		{"not json", `{nope`},
+		{"wrong schemaVersion", `{"schemaVersion":2,"id":"` + uuid.New().String() + `","type":"task.created","occurredAt":"2026-10-13T09:00:00Z","payload":{}}`},
+		{"missing id", `{"schemaVersion":1,"type":"task.created","occurredAt":"2026-10-13T09:00:00Z","payload":{}}`},
+		{"unknown type", `{"schemaVersion":1,"id":"` + uuid.New().String() + `","type":"task.nuked","occurredAt":"2026-10-13T09:00:00Z","payload":{}}`},
+		{"missing occurredAt", `{"schemaVersion":1,"id":"` + uuid.New().String() + `","type":"task.created","payload":{}}`},
+	}
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			if _, err := ParseEnvelope([]byte(tc.raw)); err == nil {
+				t.Errorf("ParseEnvelope(%s) = nil error, want fail", tc.name)
+			}
+		})
+	}
+}
+
+func TestCompensatingEnvelope_NewIDAndShape(t *testing.T) {
+	taskID := uuid.MustParse("c7c7c7c7-7777-4777-8777-777777777777")
+	assignee := FailUserID
+	env := CompensatingEnvelope(taskID, assignee, "retry x3 het", time.Now())
+	if env.Type != model.ActionTaskAssignmentFailed {
+		t.Errorf("type = %q", env.Type)
+	}
+	if env.ID == uuid.Nil {
+		t.Error("compensating id phải MỚI (go sinh — producer lúc này)")
+	}
+	raw, err := env.Marshal()
+	if err != nil {
+		t.Fatalf("marshal: %v", err)
+	}
+	back, err := ParseEnvelope(raw)
+	if err != nil {
+		t.Fatalf("round-trip parse: %v", err)
+	}
+	if back.ID != env.ID || back.Type != env.Type {
+		t.Errorf("round-trip lệch: %+v vs %+v", back, env)
+	}
+}
+
+func TestNewDLQMessage_WrapsOriginal(t *testing.T) {
+	original := []byte(`{"schemaVersion":1}`)
+	now := time.Now()
+	m := NewDLQMessage(original, "boom", 3, now)
+	if m.SchemaVersion != 1 {
+		t.Errorf("schemaVersion = %d, want 1", m.SchemaVersion)
+	}
+	if string(m.OriginalEvent) != string(original) {
+		t.Errorf("originalEvent = %s, want nguyên văn message gốc", m.OriginalEvent)
+	}
+	if m.Error.Reason != "boom" || m.Error.Retries != 3 || m.Error.FailedAt.IsZero() {
+		t.Errorf("DLQError = %+v, want reason/retries/failedAt đủ", m.Error)
+	}
+}

package/stack-template/services/go-svc/internal/consumer/handler.go

@@ -0,0 +1,91 @@
+package consumer
+
+// handler.go — xử lý 1 envelope thành activity row (đồng mức app; idempotency
+// nằm ở DB: InsertEvent ON CONFLICT DO NOTHING bằng envelope id).
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"log/slog"
+
+	"github.com/google/uuid"
+
+	"github.com/wakii-dev/architecture-overview/services/go-svc/internal/model"
+	"github.com/wakii-dev/architecture-overview/services/go-svc/internal/resolve"
+)
+
+// FailUserID — fixture user svc-fail (fail@demo.local, users.json SF-1).
+// Consume task.assigned có assigneeId = user này → Handler CỐ TÌNH fail
+// (deterministic cho e2e saga SF-5: retry ×3 → compensating → DLQ).
+var FailUserID = uuid.MustParse("55555555-5555-4555-8555-555555555555")
+
+// Store — phần schema activity consumer cần (Store thật implement ngầm).
+type Store interface {
+	InsertEvent(ctx context.Context, e *model.Event) error
+}
+
+// Tasks — phần readonly schema tasks consumer cần (TaskTitle display field).
+type Tasks interface {
+	TaskTitle(ctx context.Context, id uuid.UUID) (string, error)
+}
+
+// Handler consume 1 envelope: filter-by-type → fail hook → resolve display
+// fields best-effort → INSERT activity. KHÔNG commit offset ở đây (runner lo).
+type Handler struct {
+	Store    Store
+	Tasks    Tasks
+	Resolver *resolve.Resolver // ServiceUserName — enrich bằng service-token
+	Log      *slog.Logger
+}
+
+// Handle xử lý 1 envelope. Return nil = OK (kể cả duplicate idempotency —
+// DB DO NOTHING); return error = caller retry → DLQ.
+func (h *Handler) Handle(ctx context.Context, env Envelope) error {
+	// Filter-by-type (task-events.md consumer groups): group go-svc-activity
+	// nhận MỌI type TRỪ task.assignment_failed (compensating là của node).
+	if env.Type == model.ActionTaskAssignmentFailed {
+		h.Log.Info("skip assignment_failed (filter-by-type)", "eventId", env.ID.String())
+		return nil
+	}
+
+	var p taskUserPayload
+	if err := json.Unmarshal(env.Payload, &p); err != nil {
+		return fmt.Errorf("decode payload %s: %w", env.Type, err)
+	}
+	if p.TaskID == uuid.Nil {
+		return fmt.Errorf("payload %s thiếu taskId", env.Type)
+	}
+	if p.UserID == uuid.Nil {
+		return fmt.Errorf("payload %s thiếu userId", env.Type)
+	}
+
+	// Simulate fail hook — deterministic cho saga e2e (spec slice mục 9).
+	if env.Type == model.ActionTaskAssigned && p.AssigneeID == FailUserID {
+		return fmt.Errorf("simulate notify fail (assigneeId=%s — fixture svc-fail)", p.AssigneeID)
+	}
+
+	ev := &model.Event{
+		ID:        env.ID, // envelope id — KHÔNG sinh mới (khóa idempotency)
+		TaskID:    p.TaskID,
+		UserID:    p.UserID,
+		Action:    env.Type,
+		Timestamp: env.OccurredAt.UTC(),
+	}
+	// Display fields best-effort lúc consume — spring/tasks down → "" (feed
+	// vẫn render, resolver trả thử lại lúc đọc — feed.go).
+	ev.UserName = h.Resolver.ServiceUserName(ctx, p.UserID)
+	if title, err := h.Tasks.TaskTitle(ctx, p.TaskID); err == nil {
+		ev.TaskTitle = title
+	}
+
+	if err := h.Store.InsertEvent(ctx, ev); err != nil {
+		return fmt.Errorf("insert activity: %w", err)
+	}
+	h.Log.Info("event consumed",
+		slog.String("eventId", env.ID.String()),
+		slog.String("taskId", p.TaskID.String()),
+		slog.String("action", env.Type),
+	)
+	return nil
+}

package/stack-template/services/go-svc/internal/consumer/handler_test.go

@@ -0,0 +1,136 @@
+package consumer
+
+// handler_test.go — unit handler không broker: golden fixture → activity row
+// đúng; filter-by-type skip; fail hook deterministic; envelope id KHÔNG bị sinh mới.
+
+import (
+	"context"
+	"log/slog"
+	"sync"
+	"testing"
+	"time"
+
+	"github.com/google/uuid"
+
+	"github.com/wakii-dev/architecture-overview/services/go-svc/internal/model"
+	"github.com/wakii-dev/architecture-overview/services/go-svc/internal/resolve"
+)
+
+// fakeEventStore — bắt event consumer insert (fake riêng của package consumer —
+// không đụng fakes_test.go của package api).
+type fakeEventStore struct {
+	mu     sync.Mutex
+	events []model.Event
+	err    error
+}
+
+func (f *fakeEventStore) InsertEvent(_ context.Context, e *model.Event) error {
+	f.mu.Lock()
+	defer f.mu.Unlock()
+	if f.err != nil {
+		return f.err
+	}
+	f.events = append(f.events, *e)
+	return nil
+}
+
+type fakeTaskTitles struct{ titles map[uuid.UUID]string }
+
+func (f fakeTaskTitles) TaskTitle(_ context.Context, id uuid.UUID) (string, error) {
+	return f.titles[id], nil
+}
+
+func newTestHandler(store *fakeEventStore) *Handler {
+	return &Handler{
+		Store: store,
+		Tasks: fakeTaskTitles{titles: map[uuid.UUID]string{
+			uuid.MustParse("c7c7c7c7-7777-4777-8777-777777777777"): "Ship Kafka foundation",
+		}},
+		Resolver: resolve.New("http://spring-unused"), // không token source → userName "" (degraded)
+		Log:      slog.Default(),
+	}
+}
+
+func TestHandler_GoldenAssignedFixtureInsertsWithEnvelopeID(t *testing.T) {
+	store := &fakeEventStore{}
+	h := newTestHandler(store)
+
+	env, err := ParseEnvelope(loadFixture(t, "task.assigned.json"))
+	if err != nil {
+		t.Fatalf("parse fixture: %v", err)
+	}
+	if err := h.Handle(context.Background(), env); err != nil {
+		t.Fatalf("handle: %v", err)
+	}
+	if len(store.events) != 1 {
+		t.Fatalf("events = %d, want 1", len(store.events))
+	}
+	ev := store.events[0]
+	if ev.ID != env.ID {
+		t.Errorf("event id = %s, want envelope id %s (KHÔNG sinh mới — khóa idempotency)", ev.ID, env.ID)
+	}
+	if ev.Action != model.ActionTaskAssigned {
+		t.Errorf("action = %q", ev.Action)
+	}
+	if ev.TaskTitle != "Ship Kafka foundation" {
+		t.Errorf("taskTitle = %q, want từ readonly lookup", ev.TaskTitle)
+	}
+	if !ev.Timestamp.Equal(env.OccurredAt.UTC()) {
+		t.Errorf("timestamp = %v, want occurredAt %v", ev.Timestamp, env.OccurredAt)
+	}
+}
+
+func TestHandler_SkipsAssignmentFailedByType(t *testing.T) {
+	store := &fakeEventStore{}
+	h := newTestHandler(store)
+
+	env, err := ParseEnvelope(loadFixture(t, "task.assignment_failed.json"))
+	if err != nil {
+		t.Fatalf("parse fixture: %v", err)
+	}
+	if err := h.Handle(context.Background(), env); err != nil {
+		t.Fatalf("filter-by-type phải SKIP (nil), got %v", err)
+	}
+	if len(store.events) != 0 {
+		t.Errorf("assignment_failed KHÔNG được ghi activity, got %d rows", len(store.events))
+	}
+}
+
+func TestHandler_FailHookSvcFailDeterministic(t *testing.T) {
+	store := &fakeEventStore{}
+	h := newTestHandler(store)
+
+	// Fixture task.assigned có assigneeId = bob — không fail. Thay assigneeId
+	// = svc-fail (55555555-...) → Handle PHẢI fail deterministic (saga e2e).
+	raw, err := ParseEnvelope(loadFixture(t, "task.assigned.json"))
+	if err != nil {
+		t.Fatalf("parse fixture: %v", err)
+	}
+	raw.Payload = []byte(`{"taskId":"c7c7c7c7-7777-4777-8777-777777777777","userId":"11111111-1111-4111-8111-111111111111","assigneeId":"55555555-5555-4555-8555-555555555555"}`)
+
+	if err := h.Handle(context.Background(), raw); err == nil {
+		t.Fatal("assigneeId = svc-fail → Handle phải fail (simulate hook)")
+	}
+	if len(store.events) != 0 {
+		t.Errorf("fail hook KHÔNG được ghi activity, got %d rows", len(store.events))
+	}
+}
+
+func TestHandler_PayloadMissingFieldsRejected(t *testing.T) {
+	store := &fakeEventStore{}
+	h := newTestHandler(store)
+
+	env := Envelope{
+		SchemaVersion: 1,
+		ID:            uuid.New(),
+		Type:          model.ActionTaskCreated,
+		OccurredAt:    time.Now().UTC(),
+		Payload:       []byte(`{"taskId":"c7c7c7c7-7777-4777-8777-777777777777"}`), // thiếu userId
+	}
+	if err := h.Handle(context.Background(), env); err == nil {
+		t.Fatal("payload thiếu userId phải fail")
+	}
+	if len(store.events) != 0 {
+		t.Errorf("không được insert khi payload thiếu field bắt buộc, got %d", len(store.events))
+	}
+}

package/stack-template/services/go-svc/internal/consumer/producer.go

@@ -0,0 +1,117 @@
+package consumer
+
+// producer.go — go-svc là PRODUCER lúc saga fail: publish compensating
+// `task.assignment_failed` (envelope id MỚI do go sinh — go là producer của
+// event này) vào task-events + đẩy message gốc vào task-events.dlq
+// (task-events.md delivery semantics; conventions/09 rule 7).
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"sync"
+	"time"
+
+	"github.com/google/uuid"
+	"github.com/segmentio/kafka-go"
+
+	"github.com/wakii-dev/architecture-overview/services/go-svc/internal/model"
+)
+
+// Publisher — seam test (fake trong unit test; KafkaPublisher thật trong main).
+type Publisher interface {
+	Publish(ctx context.Context, topic string, key []byte, value []byte) error
+}
+
+// KafkaPublisher — Writer per topic (cache), shared transport; message key =
+// payload.taskId (task-events.md — thứ tự per-task trong partition).
+type KafkaPublisher struct {
+	brokers []string
+	mu      sync.Mutex
+	writers map[string]*kafka.Writer
+}
+
+// NewKafkaPublisher tạo publisher trỏ brokers (lazy-connect — Writer chỉ
+// mở kết nối ở lần Publish đầu; broker chưa lên = trả error, không crash).
+func NewKafkaPublisher(brokers ...string) *KafkaPublisher {
+	return &KafkaPublisher{brokers: brokers, writers: map[string]*kafka.Writer{}}
+}
+
+func (p *KafkaPublisher) writer(topic string) *kafka.Writer {
+	p.mu.Lock()
+	defer p.mu.Unlock()
+	if w, ok := p.writers[topic]; ok {
+		return w
+	}
+	w := &kafka.Writer{
+		Addr:         kafka.TCP(p.brokers...),
+		Topic:        topic,
+		Balancer:     &kafka.Hash{}, // key=taskId → cùng partition per-task
+		RequiredAcks: kafka.RequireOne,
+	}
+	p.writers[topic] = w
+	return w
+}
+
+func (p *KafkaPublisher) Publish(ctx context.Context, topic string, key, value []byte) error {
+	if err := p.writer(topic).WriteMessages(ctx, kafka.Message{Key: key, Value: value}); err != nil {
+		return fmt.Errorf("publish %s: %w", topic, err)
+	}
+	return nil
+}
+
+// Close đóng mọi writer (graceful shutdown).
+func (p *KafkaPublisher) Close() error {
+	p.mu.Lock()
+	defer p.mu.Unlock()
+	var firstErr error
+	for _, w := range p.writers {
+		if err := w.Close(); err != nil && firstErr == nil {
+			firstErr = err
+		}
+	}
+	return firstErr
+}
+
+// CompensatingEnvelope — event `task.assignment_failed` với envelope id MỚI
+// (go sinh — mỗi event 1 id, task-events.md).
+func CompensatingEnvelope(taskID, assigneeID uuid.UUID, reason string, now time.Time) Envelope {
+	payload, _ := json.Marshal(assignmentFailedPayload{
+		TaskID:     taskID,
+		AssigneeID: assigneeID,
+		Reason:     reason,
+	})
+	return Envelope{
+		SchemaVersion: SchemaVersion,
+		ID:            uuid.New(),
+		Type:          model.ActionTaskAssignmentFailed,
+		OccurredAt:    now.UTC(),
+		Payload:       payload,
+	}
+}
+
+// DLQMessage — message gốc (raw) + metadata lỗi vào task-events.dlq
+// (task-events.md: "Message GỐC + metadata lỗi"). KHÔNG requeue tự động.
+// OriginalEvent là STRING nguyên văn (không phải RawMessage): poison message
+// vốn KHÔNG phải JSON hợp lệ — RawMessage làm json.Marshal của wrapper fail
+// im lặng → DLQ nhận bytes rỗng (bug đã bắt bằng unit test).
+type DLQMessage struct {
+	SchemaVersion int      `json:"schemaVersion"`
+	OriginalEvent string   `json:"originalEvent"`
+	Error         DLQError `json:"error"`
+}
+
+// DLQError — metadata lỗi đi kèm event gốc trong DLQ.
+type DLQError struct {
+	Reason   string    `json:"reason"`
+	Retries  int       `json:"retries"`
+	FailedAt time.Time `json:"failedAt"`
+}
+
+func NewDLQMessage(original []byte, reason string, retries int, now time.Time) DLQMessage {
+	return DLQMessage{
+		SchemaVersion: SchemaVersion,
+		OriginalEvent: string(original),
+		Error:         DLQError{Reason: reason, Retries: retries, FailedAt: now.UTC()},
+	}
+}

package/stack-template/services/go-svc/internal/consumer/runner.go

@@ -0,0 +1,194 @@
+package consumer
+
+// runner.go — vòng lặp consume: FetchMessage → Handle (retry ×3 in-memory)
+// → hết lượt: compensating `task.assignment_failed` (chỉ cho task.assigned —
+// saga semantics; DB down sai rét compensating = mark nhầm task) + DLQ message
+// gốc → CommitMessages CUỐI CÙNG (manual commit SAU khi xử lý xong/đưa DLQ —
+// conventions/09 rule 5: commit trước = crash mất event). Publish DLQ/
+// compensating FAIL → KHÔNG commit (message còn nguyên ở topic chính — commit
+// lúc này = mất vĩnh viễn, không còn đâu re-consume; at-least-once + DB
+// idempotency lo redelivery an toàn).
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"log/slog"
+	"time"
+
+	"github.com/google/uuid"
+	"github.com/segmentio/kafka-go"
+
+	"github.com/wakii-dev/architecture-overview/services/go-svc/internal/model"
+)
+
+const (
+	// RetryMax — in-memory ×3 (ADR-0008 simplification có chủ đích; production:
+	// retry topic + backoff lâu).
+	RetryMax = 3
+	// RetryBackoff — backoff giữa các lần retry (demo: ngắn để e2e không chờ).
+	RetryBackoff = 500 * time.Millisecond
+)
+
+// MessageSource — seam thay kafka.Reader trong unit test (FetchMessage +
+// CommitMessages đúng shape segmentio).
+type MessageSource interface {
+	FetchMessage(ctx context.Context) (kafka.Message, error)
+	CommitMessages(ctx context.Context, msgs ...kafka.Message) error
+}
+
+// Runner chạy consumer loop cho 1 group.
+type Runner struct {
+	Reader    MessageSource
+	Handler   *Handler
+	Publisher Publisher
+	Topic     string // task-events — nơi publish compensating
+	DLQTopic  string // task-events.dlq
+	Log       *slog.Logger
+
+	// inject được trong test (default: RetryMax / RetryBackoff)
+	RetryMaxN    int
+	RetryBackoff time.Duration
+}
+
+// NewReader dựng kafka.Reader thật (consumer group + earliest — task-events.md).
+func NewReader(brokers []string, group, topic string) *kafka.Reader {
+	return kafka.NewReader(kafka.ReaderConfig{
+		Brokers:     brokers,
+		GroupID:     group,
+		GroupTopics: []string{topic},
+		// auto.offset.reset earliest — consumer mới đọc lại từ đầu (idempotency
+		// lo duplicates — task-events.md delivery semantics).
+		StartOffset: kafka.FirstOffset,
+		MinBytes:    1,
+		MaxBytes:    1 << 20, // 1MB — envelope nhỏ, không cần lớn hơn
+	})
+}
+
+// Run chạy tới khi ctx huỷ (graceful shutdown từ main). Không return error
+// thường — log là đủ (consumer down ≠ service down, lazy-connect convention).
+func (r *Runner) Run(ctx context.Context) {
+	retryMax := r.RetryMaxN
+	if retryMax <= 0 {
+		retryMax = RetryMax
+	}
+	backoff := r.RetryBackoff
+	if backoff <= 0 {
+		backoff = RetryBackoff
+	}
+
+	for {
+		msg, err := r.Reader.FetchMessage(ctx)
+		if err != nil {
+			if ctx.Err() != nil || errors.Is(err, context.Canceled) {
+				r.Log.Info("consumer stopped", "reason", ctx.Err())
+				return
+			}
+			// broker chưa lên / disconnect tạm — retry vòng kế (lazy-connect,
+			// conventions/09 rule 1: KHÔNG crash, KHÔNG fallback im lặng).
+			r.Log.Warn("fetch message failed — retry vòng kế", "err", err.Error())
+			select {
+			case <-ctx.Done():
+				return
+			case <-time.After(time.Second):
+			}
+			continue
+		}
+
+		procErr := r.processWithRetry(ctx, msg, retryMax, backoff)
+		if procErr != nil {
+			// Publish DLQ/compensating fail → SKIP commit: message gốc chỉ còn
+			// ở topic chính — commit giờ = mất vĩnh viễn cả gốc lẫn compensating
+			// (P1 code-review SF-3). Giữ offset chưa commit → redelivery sau
+			// restart/rebalance; DB idempotency (ON CONFLICT envelope id) lo
+			// insert trùng. KHÔNG block partition in-session — vòng kế vẫn fetch
+			// message sau.
+			if dlqErr := r.toDLQ(ctx, msg, procErr, retryMax); dlqErr != nil {
+				r.Log.Error("đưa DLQ thất bại — KHÔNG commit, giữ message chờ redelivery",
+					"eventId", string(msg.Key), "err", dlqErr.Error())
+				continue
+			}
+		}
+
+		// Manual commit SAU khi xử lý xong (DB insert đã commit) hoặc message
+		// gốc đã an toàn ở DLQ — at-least-once; idempotency lo redelivery.
+		if err := r.Reader.CommitMessages(ctx, msg); err != nil {
+			r.Log.Error("commit offset failed — message sẽ re-consume sau restart",
+				"eventId", string(msg.Key), "err", err.Error())
+		}
+	}
+}
+
+// processWithRetry: parse → Handle retry ×3. Parse fail = poison → trả error
+// ngay (retry vô ích — DLQ trực tiếp). Trả nil khi OK (kể cả filter-skip).
+func (r *Runner) processWithRetry(ctx context.Context, msg kafka.Message, retryMax int, backoff time.Duration) error {
+	env, err := ParseEnvelope(msg.Value)
+	if err != nil {
+		return &poisonError{reason: err.Error()}
+	}
+
+	var lastErr error
+	for attempt := 1; attempt <= retryMax; attempt++ {
+		if err := r.Handler.Handle(ctx, env); err == nil {
+			return nil
+		} else {
+			lastErr = err
+			r.Log.Warn("handle failed — retry",
+				"eventId", env.ID.String(), "attempt", attempt, "err", err.Error())
+		}
+		select {
+		case <-ctx.Done():
+			return lastErr
+		case <-time.After(backoff):
+		}
+	}
+	return lastErr
+}
+
+// poisonError — envelope sai shape/schema: KHÔNG retry (đưa thẳng DLQ).
+type poisonError struct{ reason string }
+
+func (e *poisonError) Error() string { return "poison message: " + e.reason }
+
+// toDLQ — saga fail: publish compensating (nếu nguồn là task.assigned) rồi
+// đẩy message gốc + metadata vào DLQ. Return nil CHỈ KHI mọi publish cần
+// thiết thành công → caller được phép commit offset. Return error (broker
+// fail / marshal fail) → caller SKIP commit — KHÔNG crash, KHÔNG block
+// partition (conventions/09 rule 7), message được redelivery thay vì mất.
+func (r *Runner) toDLQ(ctx context.Context, msg kafka.Message, procErr error, retryMax int) error {
+	reason := procErr.Error()
+
+	// Compensating CHỈ cho task.assigned fail (saga choreography — node
+	// compensation consumer UPDATE conditional). Poison/DB-down của type khác
+	// KHÔNG được mark task assignment_failed.
+	var env Envelope
+	var poison *poisonError
+	if !errors.As(procErr, &poison) {
+		if e, err := ParseEnvelope(msg.Value); err == nil && e.Type == model.ActionTaskAssigned {
+			env = e
+		}
+	}
+	if env.ID != uuid.Nil {
+		var p taskUserPayload
+		if json.Unmarshal(env.Payload, &p) == nil && p.TaskID != uuid.Nil {
+			comp := CompensatingEnvelope(p.TaskID, p.AssigneeID, reason, time.Now())
+			raw, err := comp.Marshal()
+			if err != nil {
+				return fmt.Errorf("marshal compensating: %w", err)
+			}
+			if err := r.Publisher.Publish(ctx, r.Topic, msg.Key, raw); err != nil {
+				return fmt.Errorf("publish compensating: %w", err)
+			}
+			r.Log.Warn("compensating event published",
+				"eventId", comp.ID.String(), "taskId", p.TaskID.String())
+		}
+	}
+
+	dlq, _ := json.Marshal(NewDLQMessage(msg.Value, reason, retryMax, time.Now()))
+	if err := r.Publisher.Publish(ctx, r.DLQTopic, msg.Key, dlq); err != nil {
+		return fmt.Errorf("publish DLQ: %w", err)
+	}
+	r.Log.Warn("message gốc đưa DLQ", "reason", reason)
+	return nil
+}