create-wakii-stack 0.0.0-stage → 0.1.0

package/stack-template/services/go-svc/internal/resolve/token.go

@@ -0,0 +1,130 @@
+package resolve
+
+// token.go — service-token cho consumer path (story FI-76 SF-3).
+// go consumer KHÔNG có HTTP request để passthrough Authorization như REST cũ —
+// tự login fixture service user `svc-activity` (AUTH_MOCK_URL +
+// SVC_ACTIVITY_PASSWORD) lấy JWT, cache, lazy re-login khi 401/expiry.
+// Boot-time: retry backoff, KHÔNG crash nếu auth-mock chưa lên (go chỉ
+// depends_on postgres — lazy-connect, conventions/09 rule 1).
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"fmt"
+	"log/slog"
+	"net/http"
+	"sync"
+	"time"
+)
+
+const (
+	tokenLoginTimeout = 3 * time.Second
+	// tokenCacheTTL — JWT auth-mock TTL 8h (token contract) nhưng cache ngắn
+	// hơn chủ động: 30 phút đủ demo, hết hạn → login lại trong lần dùng kế.
+	tokenCacheTTL = 30 * time.Minute
+	// bootRetry cadence — auth-mock down lúc boot là trạng thái BÌNH THƯỜNG
+	// (không service nào depends_on service nào qua kafka chain).
+	bootRetryBackoff = 5 * time.Second
+	bootRetryMax     = 12 // ~1 phút rồi từng bước theo CI poll; sau đó Token() lazy thử lại
+)
+
+// TokenSource login + cache service JWT (thread-safe).
+type TokenSource struct {
+	authURL  string // vd http://auth-mock:8090
+	email    string // svc-activity@demo.local (fixture users.json)
+	password string // SVC_ACTIVITY_PASSWORD — khớp AUTH_MOCK_DEV_PASSWORD
+	client   *http.Client
+
+	// warmup retry inject được trong test (default: bootRetryBackoff/Max)
+	retryBackoff time.Duration
+	retryMax     int
+
+	mu     sync.Mutex
+	token  string
+	expire time.Time
+}
+
+// NewTokenSource tạo token source cho service user.
+func NewTokenSource(authURL, email, password string) *TokenSource {
+	return &TokenSource{
+		authURL:      authURL,
+		email:        email,
+		password:     password,
+		client:       &http.Client{Timeout: tokenLoginTimeout},
+		retryBackoff: bootRetryBackoff,
+		retryMax:     bootRetryMax,
+	}
+}
+
+// Warmup login sớm lúc boot với retry backoff — chỉ LOG warn khi chưa được,
+// KHÔNG trả error ra caller (consumer vẫn start; Token() lazy thử lại).
+func (t *TokenSource) Warmup(ctx context.Context, log *slog.Logger) {
+	for i := 1; i <= t.retryMax; i++ {
+		if ctx.Err() != nil {
+			return
+		}
+		if _, err := t.Token(ctx); err == nil {
+			return
+		}
+		if log != nil {
+			log.Warn("service-token warmup retry (auth-mock chưa lên?)", "attempt", i)
+		}
+		select {
+		case <-ctx.Done():
+			return
+		case <-time.After(t.retryBackoff):
+		}
+	}
+}
+
+// Token trả JWT còn hạn; hết hạn/chưa có → login (lazy).
+func (t *TokenSource) Token(ctx context.Context) (string, error) {
+	t.mu.Lock()
+	defer t.mu.Unlock()
+	if t.token != "" && time.Now().Before(t.expire) {
+		return t.token, nil
+	}
+	tok, err := t.login(ctx)
+	if err != nil {
+		return "", err
+	}
+	t.token = tok
+	t.expire = time.Now().Add(tokenCacheTTL)
+	return t.token, nil
+}
+
+// Invalidate xoá cache — gọi khi resolver gặp 401 → lần dùng kế login lại.
+func (t *TokenSource) Invalidate() {
+	t.mu.Lock()
+	defer t.mu.Unlock()
+	t.token = ""
+	t.expire = time.Time{}
+}
+
+func (t *TokenSource) login(ctx context.Context) (string, error) {
+	body, _ := json.Marshal(map[string]string{"email": t.email, "password": t.password})
+	req, err := http.NewRequestWithContext(ctx, http.MethodPost, t.authURL+"/api/auth/login", bytes.NewReader(body))
+	if err != nil {
+		return "", fmt.Errorf("build login request: %w", err)
+	}
+	req.Header.Set("Content-Type", "application/json")
+	res, err := t.client.Do(req)
+	if err != nil {
+		return "", fmt.Errorf("login auth-mock: %w", err)
+	}
+	defer res.Body.Close()
+	if res.StatusCode != http.StatusOK {
+		return "", fmt.Errorf("login auth-mock = %d", res.StatusCode)
+	}
+	var out struct {
+		AccessToken string `json:"accessToken"`
+	}
+	if err := json.NewDecoder(res.Body).Decode(&out); err != nil {
+		return "", fmt.Errorf("decode login response: %w", err)
+	}
+	if out.AccessToken == "" {
+		return "", fmt.Errorf("login response thiếu accessToken")
+	}
+	return out.AccessToken, nil
+}

package/stack-template/services/go-svc/internal/resolve/token_test.go

@@ -0,0 +1,151 @@
+package resolve
+
+// token_test.go — service-token: login + cache, 401 → lazy re-login,
+// warmup retry KHÔNG crash khi auth-mock down lúc boot (ACCEPTANCE context pack).
+
+import (
+	"context"
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"strconv"
+	"sync/atomic"
+	"testing"
+	"time"
+
+	"github.com/google/uuid"
+)
+
+func fakeAuth(t *testing.T, logins *atomic.Int32) *httptest.Server {
+	t.Helper()
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if r.URL.Path != "/api/auth/login" || r.Method != http.MethodPost {
+			http.NotFound(w, r)
+			return
+		}
+		var in struct{ Email, Password string }
+		_ = json.NewDecoder(r.Body).Decode(&in)
+		if in.Password == "" {
+			w.WriteHeader(http.StatusUnauthorized)
+			return
+		}
+		logins.Add(1)
+		w.Header().Set("Content-Type", "application/json")
+		_, _ = w.Write([]byte(`{"accessToken":"tok-` + strconv.Itoa(int(logins.Load())) + `","tokenType":"bearer"}`))
+	}))
+	t.Cleanup(srv.Close)
+	return srv
+}
+
+func TestTokenSource_LoginAndCache(t *testing.T) {
+	var logins atomic.Int32
+	srv := fakeAuth(t, &logins)
+	ts := NewTokenSource(srv.URL, "svc-activity@demo.local", "demo-password")
+
+	tok1, err := ts.Token(context.Background())
+	if err != nil {
+		t.Fatalf("token: %v", err)
+	}
+	tok2, err := ts.Token(context.Background())
+	if err != nil {
+		t.Fatalf("token lần 2: %v", err)
+	}
+	if tok1 != tok2 {
+		t.Errorf("token đổi giữa 2 lần gọi trong TTL: %q vs %q", tok1, tok2)
+	}
+	if logins.Load() != 1 {
+		t.Errorf("logins = %d, want 1 (cache JWT)", logins.Load())
+	}
+}
+
+func TestTokenSource_InvalidateLazyRelogin(t *testing.T) {
+	var logins atomic.Int32
+	srv := fakeAuth(t, &logins)
+	ts := NewTokenSource(srv.URL, "svc-activity@demo.local", "demo-password")
+
+	if _, err := ts.Token(context.Background()); err != nil {
+		t.Fatalf("token: %v", err)
+	}
+	ts.Invalidate() // resolver gặp 401 → invalidate
+	tok, err := ts.Token(context.Background())
+	if err != nil {
+		t.Fatalf("token sau invalidate: %v", err)
+	}
+	if tok != "tok-2" {
+		t.Errorf("token = %q, want tok-2 (lazy re-login)", tok)
+	}
+	if logins.Load() != 2 {
+		t.Errorf("logins = %d, want 2", logins.Load())
+	}
+}
+
+func TestTokenSource_WarmupRetriesWithoutCrash(t *testing.T) {
+	var logins atomic.Int32
+	srv := fakeAuth(t, &logins)
+	ts := NewTokenSource(srv.URL, "svc-activity@demo.local", "demo-password")
+	ts.retryBackoff = time.Millisecond
+	ts.retryMax = 3
+
+	// auth-mock down lúc đầu — đóng tạm bằng wrapper trả lỗi: dùng URL sai
+	// rồi khôi phục không tiện; thay vào đó verify retry path với retryMax
+	// nhỏ trên server SỐNG (login ngay vòng 1) + verify KHÔNG crash khi
+	// server chết hẳn:
+	dead := NewTokenSource("http://127.0.0.1:1", "svc-activity@demo.local", "demo-password")
+	dead.retryBackoff = time.Millisecond
+	dead.retryMax = 2
+	dead.Warmup(context.Background(), nil) // phải return, không panic
+
+	if _, err := ts.Token(context.Background()); err != nil {
+		t.Fatalf("token sau warmup: %v", err)
+	}
+	if logins.Load() < 1 {
+		t.Errorf("logins = %d, want >= 1", logins.Load())
+	}
+}
+
+func TestServiceUserName_EnrichAndLazyReloginOn401(t *testing.T) {
+	var logins atomic.Int32
+	auth := fakeAuth(t, &logins)
+	unauthorized := atomic.Bool{}
+
+	spring := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		authz := r.Header.Get("Authorization")
+		if authz == "Bearer tok-1" && unauthorized.Load() {
+			w.WriteHeader(http.StatusUnauthorized) // token service vừa bị quay lại
+			return
+		}
+		if authz == "" {
+			w.WriteHeader(http.StatusUnauthorized)
+			return
+		}
+		w.Header().Set("Content-Type", "application/json")
+		_, _ = w.Write([]byte(`{"displayName":"Svc Activity (service user)"}`))
+	}))
+	t.Cleanup(spring.Close)
+
+	ts := NewTokenSource(auth.URL, "svc-activity@demo.local", "demo-password")
+	r := New(spring.URL).WithServiceToken(ts)
+
+	// Lần 1: enrich thành công bằng service-token (user bob — cache miss)
+	bob := uuid.MustParse("22222222-2222-4222-8222-222222222222")
+	if got := r.ServiceUserName(context.Background(), bob); got != "Svc Activity (service user)" {
+		t.Fatalf("userName = %q, want displayName qua service-token", got)
+	}
+	// Token bị spring từ chối (user carol — cache miss bắt fetch mới) → 401
+	// → Invalidate + lazy re-login → thử lại thành công
+	carol := uuid.MustParse("33333333-3333-4333-8333-333333333333")
+	unauthorized.Store(true)
+	if got := r.ServiceUserName(context.Background(), carol); got != "Svc Activity (service user)" {
+		t.Fatalf("userName sau 401 = %q, want re-login rồi enrich lại", got)
+	}
+	if logins.Load() < 2 {
+		t.Errorf("logins = %d, want >= 2 (lazy re-login)", logins.Load())
+	}
+}
+
+func TestServiceUserName_NoTokenSourceDegradedEmpty(t *testing.T) {
+	r := New("http://unused")
+	if got := r.ServiceUserName(context.Background(), uuid.MustParse("44444444-4444-4444-8444-444444444444")); got != "" {
+		t.Errorf("userName = %q, want \"\" (không token source — degraded trung thực)", got)
+	}
+}

package/stack-template/services/go-svc/internal/store/events.go

@@ -0,0 +1,71 @@
+package store
+
+import (
+	"context"
+	"fmt"
+
+	"github.com/wakii-dev/architecture-overview/services/go-svc/internal/model"
+)
+
+// ErrTasksUnavailable deprecated — sentinel chuyển sang internal/apperr
+// (dùng chung api ↔ store không import cycle). Giữ alias cho tiện đọc.
+// (Không export thêm lỗi mới từ package store.)
+
+// InsertEvent persist event (owner conn — go_svc owns schema activity).
+// Idempotency (conventions/09 rule 4): e.ID là envelope id do producer sinh
+// (node-svc outbox, mỗi event 1 id) — at-least-once redelivery cùng event →
+// ON CONFLICT DO NOTHING, KHÔNG nhân đôi feed. KHÔNG sinh id ở đây (api UUID
+// ingest đã thanh lý — id luôn đến từ envelope).
+func (s *Store) InsertEvent(ctx context.Context, e *model.Event) error {
+	tag, err := s.owner.ExecContext(ctx, `
+		INSERT INTO activity.events (id, task_id, user_id, action, event_ts, user_name, task_title)
+		VALUES ($1, $2, $3, $4, $5, $6, $7)
+		ON CONFLICT (id) DO NOTHING`,
+		e.ID, e.TaskID, e.UserID, e.Action, e.Timestamp, e.UserName, e.TaskTitle)
+	if err != nil {
+		return fmt.Errorf("insert event: %w", err)
+	}
+	if n, raErr := tag.RowsAffected(); raErr == nil && n == 0 {
+		s.log.Info("event duplicate skipped (idempotency)", "eventId", e.ID.String())
+	}
+	return nil
+}
+
+// ListEvents trả feed (mới nhất trước) + total (conventions: limit đã clamp ở handler).
+func (s *Store) ListEvents(ctx context.Context, limit, offset int) ([]model.Event, int, error) {
+	var total int
+	if err := s.owner.QueryRowContext(ctx,
+		`SELECT COUNT(*) FROM activity.events`).Scan(&total); err != nil {
+		return nil, 0, fmt.Errorf("count events: %w", err)
+	}
+	rows, err := s.owner.QueryContext(ctx, `
+		SELECT id, task_id, user_id, action, event_ts, user_name, task_title
+		FROM activity.events
+		ORDER BY event_ts DESC, id DESC
+		LIMIT $1 OFFSET $2`, limit, offset)
+	if err != nil {
+		return nil, 0, fmt.Errorf("list events: %w", err)
+	}
+	defer rows.Close()
+
+	var out []model.Event
+	for rows.Next() {
+		var e model.Event
+		if err := rows.Scan(&e.ID, &e.TaskID, &e.UserID, &e.Action, &e.Timestamp, &e.UserName, &e.TaskTitle); err != nil {
+			return nil, 0, fmt.Errorf("scan event: %w", err)
+		}
+		out = append(out, e)
+	}
+	return out, total, rows.Err()
+}
+
+// CountRecent24h — số event trong 24h qua (owner conn — schema activity của mình).
+func (s *Store) CountRecent24h(ctx context.Context) (int, error) {
+	var n int
+	err := s.owner.QueryRowContext(ctx,
+		`SELECT COUNT(*) FROM activity.events WHERE event_ts > now() - interval '24 hours'`).Scan(&n)
+	if err != nil {
+		return 0, fmt.Errorf("count recent events: %w", err)
+	}
+	return n, nil
+}

package/stack-template/services/go-svc/internal/store/migrate.go

@@ -0,0 +1,90 @@
+package store
+
+import (
+	"context"
+	"embed"
+	"fmt"
+	"io/fs"
+	"sort"
+	"strconv"
+	"strings"
+)
+
+//go:embed migrations/*.sql
+var migrationsFS embed.FS
+
+// Migrate chạy embedded migrations lên schema activity (go_svc là owner).
+// Idempotent: bảng activity.schema_migrations track version đã apply.
+func (s *Store) Migrate(ctx context.Context) error {
+	if _, err := s.owner.ExecContext(ctx, `
+		CREATE TABLE IF NOT EXISTS activity.schema_migrations (
+			version     integer PRIMARY KEY,
+			description text        NOT NULL,
+			applied_at  timestamptz NOT NULL DEFAULT now()
+		)`); err != nil {
+		return fmt.Errorf("ensure schema_migrations: %w", err)
+	}
+
+	var current int
+	if err := s.owner.QueryRowContext(ctx,
+		`SELECT COALESCE(MAX(version), 0) FROM activity.schema_migrations`).Scan(&current); err != nil {
+		return fmt.Errorf("read current migration version: %w", err)
+	}
+
+	entries, err := fs.Glob(migrationsFS, "migrations/*.sql")
+	if err != nil {
+		return fmt.Errorf("list migrations: %w", err)
+	}
+	sort.Strings(entries)
+
+	for _, name := range entries {
+		version, desc, err := parseMigrationName(name)
+		if err != nil {
+			return err
+		}
+		if version <= current {
+			continue
+		}
+		sqlBytes, err := migrationsFS.ReadFile(name)
+		if err != nil {
+			return fmt.Errorf("read migration %s: %w", name, err)
+		}
+		tx, err := s.owner.BeginTx(ctx, nil)
+		if err != nil {
+			return fmt.Errorf("begin migration %s: %w", name, err)
+		}
+		if _, err := tx.ExecContext(ctx, string(sqlBytes)); err != nil {
+			_ = tx.Rollback()
+			return fmt.Errorf("apply migration %s: %w", name, err)
+		}
+		if _, err := tx.ExecContext(ctx,
+			`INSERT INTO activity.schema_migrations (version, description) VALUES ($1, $2)`,
+			version, desc); err != nil {
+			_ = tx.Rollback()
+			return fmt.Errorf("record migration %s: %w", name, err)
+		}
+		if err := tx.Commit(); err != nil {
+			return fmt.Errorf("commit migration %s: %w", name, err)
+		}
+		s.log.Info("migration applied", "version", version, "description", desc)
+	}
+	s.migrated = true
+	return nil
+}
+
+// parseMigrationName parse "0001_create_events.sql" → (1, "create_events").
+func parseMigrationName(name string) (int, string, error) {
+	base := strings.TrimSuffix(strings.TrimPrefix(name, "migrations/"), ".sql")
+	parts := strings.SplitN(base, "_", 2)
+	if len(parts) != 2 {
+		return 0, "", fmt.Errorf("migration name %q sai format NNNN_desc.sql", name)
+	}
+	version, err := strconv.Atoi(parts[0])
+	if err != nil {
+		return 0, "", fmt.Errorf("migration prefix %q không phải số: %w", parts[0], err)
+	}
+	if parts[1] == "" {
+		return 0, "", fmt.Errorf("migration %q thiếu description", name)
+	}
+	return version, parts[1], nil
+}

package/stack-template/services/go-svc/internal/store/migrate_test.go

@@ -0,0 +1,34 @@
+package store
+
+import "testing"
+
+func TestParseMigrationName(t *testing.T) {
+	cases := []struct {
+		name    string
+		version int
+		desc    string
+		wantErr bool
+	}{
+		{"migrations/0001_create_events.sql", 1, "create_events", false},
+		{"migrations/0012_add_column.sql", 12, "add_column", false},
+		{"migrations/badname.sql", 0, "", true},
+		{"migrations/0001_.sql", 0, "", true},
+		{"migrations/xx_desc.sql", 0, "", true},
+	}
+	for _, tc := range cases {
+		v, d, err := parseMigrationName(tc.name)
+		if tc.wantErr {
+			if err == nil {
+				t.Errorf("%q: expected error", tc.name)
+			}
+			continue
+		}
+		if err != nil {
+			t.Errorf("%q: unexpected err %v", tc.name, err)
+			continue
+		}
+		if v != tc.version || d != tc.desc {
+			t.Errorf("%q: got (%d,%q), want (%d,%q)", tc.name, v, d, tc.version, tc.desc)
+		}
+	}
+}

package/stack-template/services/go-svc/internal/store/migrations/0001_create_events.sql

@@ -0,0 +1,20 @@
+-- 0001 — bảng activity.events (go-svc SF-4 sở hữu schema `activity`).
+-- id do app sinh (uuid v4) — cùng quyết định canonical DDL của tasks
+-- (contracts/db/tasks-schema.sql quyết định 3): không phụ thuộc pgcrypto.
+-- user_name / task_title: display fields resolve best-effort lúc ingest
+-- (spring REST / readonly tasks) — contract activity.yaml yêu cầu feed trả đủ.
+
+CREATE TABLE IF NOT EXISTS activity.events (
+    id         uuid PRIMARY KEY,
+    task_id    uuid        NOT NULL,
+    user_id    uuid        NOT NULL,
+    action     varchar(20) NOT NULL
+               CHECK (action IN ('task.created', 'task.updated', 'task.deleted')),
+    event_ts   timestamptz NOT NULL,
+    user_name  varchar(200) NOT NULL DEFAULT '',
+    task_title varchar(200) NOT NULL DEFAULT '',
+    created_at timestamptz NOT NULL DEFAULT now()
+);
+
+CREATE INDEX IF NOT EXISTS idx_activity_events_event_ts ON activity.events (event_ts DESC);
+CREATE INDEX IF NOT EXISTS idx_activity_events_task_id  ON activity.events (task_id);

package/stack-template/services/go-svc/internal/store/migrations/0002_widen_action_cascade.sql

@@ -0,0 +1,14 @@
+-- 0002 — cụm nguyên tử activity-side cascade (story FI-76 SF-3 / Linear FI-80).
+-- Consumer Kafka ghi thêm 2 action mới qua envelope type:
+--   task.assigned (13 ký tự) + task.assignment_failed (22 ký tự > varchar(20) cũ).
+-- P0 ×2 (context pack sf-3): width + CHECK phải CÙNG migration — chỉ sửa CHECK
+-- quên width = InsertEvent chết runtime cho assignment_failed → retry ×3 → DLQ
+-- sai nguyên nhân.
+
+ALTER TABLE activity.events ALTER COLUMN action TYPE varchar(40);
+
+ALTER TABLE activity.events DROP CONSTRAINT events_action_check;
+
+ALTER TABLE activity.events ADD CONSTRAINT events_action_check
+    CHECK (action IN ('task.created', 'task.updated', 'task.deleted',
+                      'task.assigned', 'task.assignment_failed'));

package/stack-template/services/go-svc/internal/store/store.go

@@ -0,0 +1,65 @@
+// Package store — DB layer của go-svc:
+//   - owner connection (DATABASE_URL, role go_svc): schema activity — INSERT/SELECT events
+//   - readonly connection (DATABASE_READONLY_URL, role go_readonly): schema tasks — stats
+// Permission boundary: go_readonly CHỈ có SELECT trên schema tasks
+// (platform/postgres/init/01-init.sh — ALTER DEFAULT PRIVILEGES FOR ROLE node_svc).
+package store
+
+import (
+	"context"
+	"database/sql"
+	"fmt"
+	"log/slog"
+	"time"
+
+	_ "github.com/jackc/pgx/v5/stdlib" // database/sql driver "pgx"
+)
+
+// Store giữ 2 connection pool riêng biệt — mixing chúng sẽ phá permission demo.
+type Store struct {
+	owner    *sql.DB
+	readonly *sql.DB
+	log      *slog.Logger
+	migrated bool
+}
+
+// Open mở 2 pool + ping cả hai (fail-fast khi DB không reachable lúc boot).
+func Open(ctx context.Context, ownerURL, readonlyURL string, log *slog.Logger) (*Store, error) {
+	owner, err := sql.Open("pgx", ownerURL)
+	if err != nil {
+		return nil, fmt.Errorf("open owner conn: %w", err)
+	}
+	if err := owner.PingContext(ctx); err != nil {
+		return nil, fmt.Errorf("ping owner conn: %w", err)
+	}
+	ro, err := sql.Open("pgx", readonlyURL)
+	if err != nil {
+		return nil, fmt.Errorf("open readonly conn: %w", err)
+	}
+	if err := ro.PingContext(ctx); err != nil {
+		return nil, fmt.Errorf("ping readonly conn: %w", err)
+	}
+	return &Store{owner: owner, readonly: ro, log: log}, nil
+}
+
+// Close đóng cả 2 pool.
+func (s *Store) Close() error {
+	err1 := s.owner.Close()
+	err2 := s.readonly.Close()
+	if err1 != nil {
+		return err1
+	}
+	return err2
+}
+
+// Ready implements api.ReadinessChecker (conventions/02 go-svc row):
+// migration schema activity xong + SELECT thử được schema tasks (readonly role).
+// Probe có timeout 3s — DB hang không được treo readyz (P1 code-review).
+func (s *Store) Ready() error {
+	if !s.migrated {
+		return fmt.Errorf("migration schema activity not applied")
+	}
+	ctx, cancel := context.WithTimeout(context.Background(), 3*time.Second)
+	defer cancel()
+	return s.Probe(ctx)
+}

package/stack-template/services/go-svc/internal/store/tasks.go

@@ -0,0 +1,109 @@
+package store
+
+import (
+	"context"
+	"database/sql"
+	"errors"
+	"fmt"
+
+	"github.com/google/uuid"
+
+	"github.com/wakii-dev/architecture-overview/services/go-svc/internal/apperr"
+	"github.com/wakii-dev/architecture-overview/services/go-svc/internal/model"
+)
+
+// Side của readonly connection (go_readonly): CHỈ SELECT schema tasks.
+// Query khớp chính xác canonical DDL — contracts/db/tasks-schema.sql:
+//   status varchar(20) CHECK IN ('todo','in_progress','done').
+
+// isPermissionOrMissing — phân biệt lỗi permission/schema với lỗi thật khác.
+func isPermissionOrMissing(err error) bool {
+	if err == nil {
+		return false
+	}
+	var pgErr interface{ SQLState() string }
+	if errors.As(err, &pgErr) {
+		switch pgErr.SQLState() {
+		case "42501": // insufficient_privilege — readonly grant bị revoke
+			return true
+		case "42P01": // undefined_table — SF-2 chưa migrate
+			return true
+		case "3D000": // invalid_catalog_name — schema chưa tồn tại
+			return true
+		}
+	}
+	return false
+}
+
+// mapTasksError — lỗi đọc tasks → apperr.ErrTasksUnavailable (503) hoặc passthrough.
+func mapTasksError(err error) error {
+	if err == nil {
+		return nil
+	}
+	if isPermissionOrMissing(err) {
+		return apperr.ErrTasksUnavailable
+	}
+	return err
+}
+
+// TaskTitle lookup 1 task (readonly) — "" khi không tìm thấy/không đọc được
+// (best-effort display field, không raise).
+func (s *Store) TaskTitle(ctx context.Context, id uuid.UUID) (string, error) {
+	var title string
+	err := s.readonly.QueryRowContext(ctx,
+		`SELECT title FROM tasks.tasks WHERE id = $1`, id).Scan(&title)
+	if errors.Is(err, sql.ErrNoRows) {
+		return "", nil
+	}
+	if err != nil {
+		return "", mapTasksError(err)
+	}
+	return title, nil
+}
+
+// Stats — COUNT(*) + GROUP BY status trên tasks.tasks (readonly, canonical DDL).
+// tasks chưa tồn tại / mất grant → ErrTasksUnavailable → handler 503.
+func (s *Store) Stats(ctx context.Context) (model.TaskStats, error) {
+	var total int
+	if err := s.readonly.QueryRowContext(ctx,
+		`SELECT COUNT(*) FROM tasks.tasks`).Scan(&total); err != nil {
+		return model.TaskStats{}, mapTasksError(fmt.Errorf("count tasks: %w", err))
+	}
+
+	rows, err := s.readonly.QueryContext(ctx,
+		`SELECT status, COUNT(*) FROM tasks.tasks GROUP BY status`)
+	if err != nil {
+		return model.TaskStats{}, mapTasksError(fmt.Errorf("group tasks by status: %w", err))
+	}
+	defer rows.Close()
+
+	byStatus := map[string]int{"todo": 0, "in_progress": 0, "done": 0, "assignment_failed": 0}
+	for rows.Next() {
+		var st string
+		var n int
+		if err := rows.Scan(&st, &n); err != nil {
+			return model.TaskStats{}, fmt.Errorf("scan status row: %w", err)
+		}
+		byStatus[st] = n
+	}
+	if err := rows.Err(); err != nil {
+		return model.TaskStats{}, fmt.Errorf("iterate status rows: %w", err)
+	}
+	return model.TaskStats{TotalTasks: total, ByStatus: byStatus}, nil
+}
+
+// Probe — SELECT thử schema tasks bằng readonly role (readyz, conventions/02).
+// Bảng tồn tại nhưng RỖNG (node-svc migrate xong, chưa ai tạo task) → OK
+// (P1 code-review: sql.ErrNoRows ≠ permission/schema problem).
+func (s *Store) Probe(ctx context.Context) error {
+	var one int
+	err := s.readonly.QueryRowContext(ctx,
+		`SELECT 1 FROM tasks.tasks LIMIT 1`).Scan(&one)
+	if errors.Is(err, sql.ErrNoRows) {
+		return nil
+	}
+	if err != nil {
+		return mapTasksError(fmt.Errorf("probe schema tasks (readonly): %w", err))
+	}
+	return nil
+}