create-wakii-stack 0.0.0-stage → 0.1.0

package/stack-template/services/node-svc/src/app.ts

@@ -0,0 +1,126 @@
+// app.ts — Fastify assembly: CORS dev-profile (conventions/07), swagger UI
+// (mirror tối thiểu tasks.yaml — pattern auth-mock), error envelope chung
+// (conventions/04), JSON log shape (conventions/03), health naked + mirror,
+// CRUD /api/tasks. Tất cả dependency inject qua opts → unit test không cần
+// postgres/spring/go thật.
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import Fastify, { type FastifyBaseLogger, type FastifyError, type FastifyInstance } from 'fastify';
+import cors from '@fastify/cors';
+import swagger from '@fastify/swagger';
+import swaggerUi from '@fastify/swagger-ui';
+import type { SpringClient } from './clients/spring.js';
+import { nodeSvcLogger } from './logger.js';
+import type { Env } from './env.js';
+import { registerHealthRoutes } from './routes/health.js';
+import { registerTaskRoutes } from './routes/tasks.js';
+import type { TaskRepo } from './repo.js';
+
+export interface AppDeps {
+  env: Env;
+  repo: TaskRepo;
+  spring: SpringClient;
+}
+
+export function buildApp(deps: AppDeps): FastifyInstance {
+  const { env, repo, spring } = deps;
+  const logger = nodeSvcLogger(env.logLevel);
+
+  const app = Fastify({
+    // pino ≥9.14 Logger type ≠ FastifyBaseLogger (msgPrefix) — cast giao diện
+    // log, instance vẫn là pino shape conventions/03.
+    loggerInstance: logger as unknown as FastifyBaseLogger,
+    genReqId: (req) => {
+      // X-Request-Id từ gateway (conventions/03) — trace xuyên gateway → service
+      const header = req.headers['x-request-id'];
+      return typeof header === 'string' && header.length > 0 ? header : crypto.randomUUID();
+    },
+    bodyLimit: 64 * 1024,
+  });
+
+  // CORS dev-profile — conventions/07: origin từ CORS_DEV_ORIGIN (phẩy);
+  // rỗng (compose/prod) → origin:false = KHÔNG emit ACAO (deny-by-default).
+  const devOrigins = env.corsDevOrigin
+    .split(',')
+    .map((s) => s.trim())
+    .filter(Boolean);
+  void app.register(cors, {
+    origin: devOrigins.length > 0 ? devOrigins : false,
+    methods: ['GET', 'POST', 'PATCH', 'DELETE'],
+    allowedHeaders: ['Authorization', 'Content-Type', 'X-Request-Id'],
+  });
+
+  // Swagger UI — mirror tối thiểu của contracts/openapi/tasks.yaml (spec §11).
+  // Native: http://localhost:3001/api/tasks/docs. Qua gateway cần Bearer.
+  void app.register(swagger, {
+    openapi: {
+      info: {
+        title: 'Tasks API (node-svc)',
+        version: '0.1.0',
+        description:
+          'Task CRUD — source of truth: contracts/openapi/tasks.yaml. Bản dưới đây là mirror tối thiểu cho swagger UI.',
+      },
+      servers: [{ url: '/api/tasks' }],
+      components: {
+        securitySchemes: {
+          bearerAuth: { type: 'http', scheme: 'bearer', bearerFormat: 'JWT' },
+        },
+      },
+    },
+  });
+  void app.register(swaggerUi, { routePrefix: '/api/tasks/docs' });
+
+  // Error envelope chung (conventions/04) — map mọi error, kể cả FST_ERR_*.
+  app.setErrorHandler((err: FastifyError, request, reply) => {
+    const isValidation = Array.isArray(err.validation);
+    const status = err.statusCode && err.statusCode >= 400 ? err.statusCode : isValidation ? 400 : 500;
+    request.log[status >= 500 ? 'error' : 'warn']({ err: err.message }, 'request failed');
+    reply.status(status).send({
+      error: {
+        // FST_ERR_VALIDATION → VALIDATION_ERROR (envelope chung, conventions/04)
+        code: isValidation
+          ? 'VALIDATION_ERROR'
+          : (err.code ?? (status === 401 ? 'UNAUTHORIZED' : status === 404 ? 'NOT_FOUND' : 'INTERNAL')),
+        message: status >= 500 ? 'Internal error' : err.message,
+        requestId: request.id,
+        details: status >= 500 ? null : (err.validation ?? null),
+      },
+    });
+  });
+
+  // 404 ngoài route — cùng envelope (NOT_FOUND).
+  app.setNotFoundHandler((request, reply) => {
+    reply.status(404).send({
+      error: { code: 'NOT_FOUND', message: `Route ${request.method} ${request.url} không tồn tại`, requestId: request.id, details: null },
+    });
+  });
+
+  // Health: naked (compose healthcheck + boot-smoke) + mirror /api/tasks/*.
+  registerHealthRoutes(app, repo);
+  app.register(
+    async (scope) => {
+      registerHealthRoutes(scope, repo);
+    },
+    { prefix: '/api/tasks' },
+  );
+
+  // CRUD /api/tasks — auth guard mount trong plugin (health exempt nằm ngoài).
+  app.register(
+    async (scope) => {
+      registerTaskRoutes(scope, {
+        repo,
+        spring,
+        jwtSecret: env.jwtSecret,
+        log: (level, msg, fields) => logger[level](fields ?? {}, msg),
+      });
+    },
+    { prefix: '/api/tasks' },
+  );
+
+  return app;
+}
+
+/** Đường dẫn thư mục migration — đúng cho tsx (src/), dist/ và Docker /app/dist. */
+export function migrationsFolder(): string {
+  return path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../drizzle');
+}

package/stack-template/services/node-svc/src/clients/spring.ts

@@ -0,0 +1,53 @@
+// spring.ts — user-validation client (spec §4): GET {SPRING_SVC_URL}/api/users/users/{id} (SF-3 contract resolution — đã FIX-P0-FIRST)
+// timeout 2s. Kết quả 3 trạng thái — route map: ok→ghi, not_found→422, down→503 fail-closed.
+import type { LogFn } from '../types/log.js';
+
+export const USER_VALIDATE_TIMEOUT_MS = 2000;
+
+export type UserValidation = 'ok' | 'not_found' | 'down';
+
+export interface SpringClient {
+  validateUser(userId: string, bearerToken: string | undefined): Promise<UserValidation>;
+  /** boot-time reachability check 1 lần (readyz deviation D3 — warn-only) */
+  ping(): Promise<boolean>;
+}
+
+export class HttpSpringClient implements SpringClient {
+  constructor(
+    private readonly baseUrl: string,
+    private readonly log?: LogFn,
+  ) {}
+
+  async validateUser(userId: string, bearerToken: string | undefined): Promise<UserValidation> {
+    let res: Response;
+    try {
+      res = await fetch(`${this.baseUrl}/api/users/users/${encodeURIComponent(userId)}`, {
+        method: 'GET',
+        headers: bearerToken ? { authorization: `Bearer ${bearerToken}` } : {},
+        signal: AbortSignal.timeout(USER_VALIDATE_TIMEOUT_MS),
+      });
+    } catch (err) {
+      this.log?.('warn', 'user validation request failed', {
+        userId,
+        err: err instanceof Error ? err.message : String(err),
+      });
+      return 'down';
+    }
+    if (res.status === 200) return 'ok';
+    if (res.status === 404) return 'not_found';
+    // status khác (401/500/…) — coi dependency đang bất thường → fail-closed
+    this.log?.('warn', 'user validation unexpected status', { userId, status: res.status });
+    return 'down';
+  }
+
+  async ping(): Promise<boolean> {
+    try {
+      const res = await fetch(`${this.baseUrl}/healthz`, {
+        signal: AbortSignal.timeout(USER_VALIDATE_TIMEOUT_MS),
+      });
+      return res.ok;
+    } catch {
+      return false;
+    }
+  }
+}

package/stack-template/services/node-svc/src/compensation-consumer.test.ts

@@ -0,0 +1,157 @@
+// compensation-consumer.test.ts — logic xử lý message của consumer (SF-2 FI-79),
+// không broker: handleMessage pure với fake deps. Fixture load CHUNG
+// contracts/events/fixtures (task-events.md — 2 đầu cùng nguồn sự thật).
+// Conditional UPDATE guard (stale/idempotent) mirror ở fake store; SQL thật
+// verify ở CI boot-smoke + saga e2e.
+import { readFileSync } from 'node:fs';
+import { describe, expect, it } from 'vitest';
+import { fileURLToPath } from 'node:url';
+import { dirname, resolve } from 'node:path';
+import { handleMessage, type CompensationDeps } from './compensation-consumer.js';
+
+const here = dirname(fileURLToPath(import.meta.url));
+const FIXTURES = resolve(here, '../../../contracts/events/fixtures');
+
+function loadFixtureRaw(name: string): string {
+  return readFileSync(resolve(FIXTURES, `${name}.json`), 'utf8');
+}
+
+function fakeDeps(): CompensationDeps & {
+  marked: Array<{ taskId: string; assigneeId: string }>;
+  commits: number;
+  dlqMessages: string[];
+  markResult: boolean;
+  failTimes: number;
+} {
+  const ret = {
+    marked: [] as Array<{ taskId: string; assigneeId: string }>,
+    commits: 0,
+    dlqMessages: [] as string[],
+    markResult: true,
+    failTimes: 0,
+  };
+  const deps: CompensationDeps = {
+    store: {
+      // đọc markResult/failTimes từ ret (test mutate TRỰC TIẾP trên object trả về)
+      async markAssignmentFailed(taskId: string, assigneeId: string) {
+        ret.marked.push({ taskId, assigneeId });
+        if (ret.failTimes > 0) {
+          ret.failTimes--;
+          throw new Error('db transient error');
+        }
+        return ret.markResult; // false = stale/idempotent (guard không khớp)
+      },
+    },
+    dlq: {
+      async send(value: string) {
+        ret.dlqMessages.push(value);
+      },
+    },
+    commit: async () => {
+      ret.commits++;
+    },
+    delay: async () => {}, // instant — test không chờ backoff
+    log: () => {},
+  };
+  return Object.assign(ret, deps);
+}
+
+describe('compensation consumer — filter-by-type + conditional guard (task-events.md)', () => {
+  it('task.assignment_failed (golden fixture) → markAssignmentFailed đúng taskId+assigneeId + commit', async () => {
+    const fixture = JSON.parse(loadFixtureRaw('task.assignment_failed')) as {
+      payload: { taskId: string; assigneeId: string };
+    };
+    const deps = fakeDeps();
+    await handleMessage(loadFixtureRaw('task.assignment_failed'), deps);
+
+    expect(deps.marked).toEqual([
+      { taskId: fixture.payload.taskId, assigneeId: fixture.payload.assigneeId },
+    ]);
+    expect(deps.commits).toBe(1); // manual commit SAU khi DB op xong
+    expect(deps.dlqMessages).toHaveLength(0);
+  });
+
+  it('STALE event (assignee khác → guard không khớp) → KHÔNG đổi, vẫn commit (acceptance)', async () => {
+    const deps = fakeDeps();
+    deps.markResult = false; // conditional UPDATE match 0 row — stale assignee
+    await handleMessage(loadFixtureRaw('task.assignment_failed'), deps);
+
+    expect(deps.commits).toBe(1); // không-dổi là THÀNH CÔNG — offset vẫn tiến
+    expect(deps.dlqMessages).toHaveLength(0);
+  });
+
+  it('IDEMPOTENT replay (event lặp → match 0 row) → commit lần 2 bình thường', async () => {
+    const deps = fakeDeps();
+    await handleMessage(loadFixtureRaw('task.assignment_failed'), deps);
+    deps.markResult = false; // lần 2: status đã 'assignment_failed' → guard chặn
+    await handleMessage(loadFixtureRaw('task.assignment_failed'), deps);
+
+    expect(deps.marked).toHaveLength(2);
+    expect(deps.commits).toBe(2);
+    expect(deps.dlqMessages).toHaveLength(0);
+  });
+
+  it('type khác (task.created fixture) → KHÔNG xử lý, vẫn commit (filter-by-type)', async () => {
+    const deps = fakeDeps();
+    await handleMessage(loadFixtureRaw('task.created'), deps);
+
+    expect(deps.marked).toHaveLength(0);
+    expect(deps.commits).toBe(1);
+  });
+
+  it('JSON hỏng → thẳng DLQ (message gốc) + commit, không retry', async () => {
+    const deps = fakeDeps();
+    await handleMessage('{not-json', deps);
+
+    expect(deps.marked).toHaveLength(0);
+    expect(deps.dlqMessages).toHaveLength(1);
+    expect(deps.dlqMessages[0]).toContain('invalid_json');
+    expect(deps.dlqMessages[0]).toContain('{not-json');
+    expect(deps.commits).toBe(1);
+  });
+
+  it('payload thiếu field bắt buộc → DLQ, không retry', async () => {
+    const deps = fakeDeps();
+    const bad = JSON.stringify({
+      schemaVersion: 1,
+      id: crypto.randomUUID(),
+      type: 'task.assignment_failed',
+      occurredAt: '2026-10-13T09:20:00Z',
+      payload: { taskId: 'x' }, // thiếu assigneeId
+    });
+    await handleMessage(bad, deps);
+
+    expect(deps.marked).toHaveLength(0);
+    expect(deps.dlqMessages).toHaveLength(1);
+    expect(deps.dlqMessages[0]).toContain('invalid_payload');
+    expect(deps.commits).toBe(1);
+  });
+
+  it('DB fail ×3 → retry đúng 3 lần rồi DLQ (message gốc + metadata) + commit', async () => {
+    const fixture = JSON.parse(loadFixtureRaw('task.assignment_failed')) as Record<string, unknown>;
+    const deps = fakeDeps();
+    deps.failTimes = 99; // fail mọi attempt
+    await handleMessage(loadFixtureRaw('task.assignment_failed'), deps);
+
+    expect(deps.marked).toHaveLength(3); // retry ×3 in-memory (conventions/09 rule 7)
+    expect(deps.dlqMessages).toHaveLength(1);
+    const dlq = JSON.parse(deps.dlqMessages[0]) as {
+      dlq: { reason: string; error: string };
+      original: Record<string, unknown>;
+    };
+    expect(dlq.dlq.reason).toBe('processing_failed_after_retries');
+    expect(dlq.dlq.error).toContain('db transient error');
+    expect(dlq.original).toEqual(fixture); // message GỐC giữ nguyên (task-events.md)
+    expect(deps.commits).toBe(1); // KHÔNG block partition — commit sau DLQ
+  });
+
+  it('DB fail 1/3 lần → retry lần 2 thành công → KHÔNG DLQ', async () => {
+    const deps = fakeDeps();
+    deps.failTimes = 1;
+    await handleMessage(loadFixtureRaw('task.assignment_failed'), deps);
+
+    expect(deps.marked).toHaveLength(2);
+    expect(deps.dlqMessages).toHaveLength(0);
+    expect(deps.commits).toBe(1);
+  });
+});

package/stack-template/services/node-svc/src/compensation-consumer.ts

@@ -0,0 +1,170 @@
+// compensation-consumer.ts — node-svc compensation consumer (saga — ADR-0008).
+// Group `node-svc-compensation`, filter-by-type: CHỈ xử lý
+// `task.assignment_failed` (conventions/09 rule 6 + task-events.md), 4 type còn
+// lại commit + bỏ qua. Xử lý = conditional UPDATE (repo.markAssignmentFailed —
+// guard chống stale compensation, idempotent theo envelope id/retry).
+// Manual offset commit SAU khi DB op xong (conventions/09 rule 5). Lỗi xử lý
+// retry ×3 in-memory backoff → hết lượt: message gốc + metadata vào
+// `task-events.dlq` rồi commit (KHÔNG block partition — rule 7).
+import { Kafka, type Consumer, type Kafka as KafkaType } from 'kafkajs';
+import type { LogFn } from './types/log.js';
+
+export const COMPENSATION_GROUP = 'node-svc-compensation';
+export const DLQ_TOPIC = 'task-events.dlq';
+const RETRY_ATTEMPTS = 3;
+const RETRY_BACKOFF_MS = 200; // ×3 in-memory — backoff ngắn (demo scale)
+const CONNECT_RETRY_MS = 5000;
+
+/** Envelope 5 type — chỉ `task.assignment_failed` được xử lý. */
+interface Envelope {
+  schemaVersion?: number;
+  id?: string;
+  type?: string;
+  occurredAt?: string;
+  payload?: { taskId?: unknown; assigneeId?: unknown; [k: string]: unknown };
+}
+
+export interface CompensationDeps {
+  store: { markAssignmentFailed(taskId: string, assigneeId: string): Promise<boolean> };
+  dlq: { send(value: string): Promise<void> };
+  commit(): Promise<void>; // offset commit — CHỈ gọi sau khi DB op xong
+  log: LogFn;
+  delay?(ms: number): Promise<void>;
+}
+
+/** Xử lý 1 message thô — pure logic cho unit test (không cần broker). */
+export async function handleMessage(raw: string, deps: CompensationDeps): Promise<void> {
+  const delay = deps.delay ?? ((ms: number) => new Promise<void>((r) => setTimeout(r, ms)));
+
+  let envelope: Envelope;
+  try {
+    envelope = JSON.parse(raw) as Envelope;
+  } catch {
+    // JSON hỏng — retry vô nghĩa: thẳng DLQ (message gốc + metadata) + commit.
+    await deps.dlq.send(JSON.stringify({ dlq: { reason: 'invalid_json' }, original: raw }));
+    await deps.commit();
+    return;
+  }
+
+  // Filter-by-type (task-events.md) — type khác: KHÔNG xử lý, vẫn commit.
+  if (envelope.type !== 'task.assignment_failed') {
+    await deps.commit();
+    return;
+  }
+
+  const taskId = typeof envelope.payload?.taskId === 'string' ? envelope.payload.taskId : null;
+  const assigneeId =
+    typeof envelope.payload?.assigneeId === 'string' ? envelope.payload.assigneeId : null;
+  if (!taskId || !assigneeId) {
+    // Payload thiếu field bắt buộc — shape lệch hợp đồng: DLQ, không retry.
+    await deps.dlq.send(
+      JSON.stringify({ dlq: { reason: 'invalid_payload' }, original: envelope }),
+    );
+    await deps.commit();
+    return;
+  }
+
+  // Retry ×3 in-memory (conventions/09 rule 7) — lỗi DB tạm thì qua; hết lượt
+  // → DLQ message gốc + metadata rồi commit (không requeue, không block).
+  let lastErr: unknown;
+  for (let attempt = 1; attempt <= RETRY_ATTEMPTS; attempt++) {
+    try {
+      // false = conditional guard không khớp (stale/idempotent-replay) — vẫn là
+      // xử lý THÀNH CÔNG: event không áp dụng được là hành vi đúng, commit.
+      await deps.store.markAssignmentFailed(taskId, assigneeId);
+      await deps.commit();
+      return;
+    } catch (err) {
+      lastErr = err;
+      if (attempt < RETRY_ATTEMPTS) await delay(RETRY_BACKOFF_MS * attempt);
+    }
+  }
+
+  deps.log('error', 'compensation processing failed after retries — to DLQ', {
+    envelopeId: envelope.id,
+    taskId,
+    err: lastErr instanceof Error ? lastErr.message : String(lastErr),
+  });
+  await deps.dlq.send(
+    JSON.stringify({
+      dlq: { reason: 'processing_failed_after_retries', error: String(lastErr) },
+      original: envelope,
+    }),
+  );
+  await deps.commit();
+}
+
+export class CompensationConsumer {
+  private readonly kafka: KafkaType;
+  private consumer: Consumer | null = null;
+  private stopped = false;
+
+  constructor(
+    private readonly brokers: string[],
+    private readonly deps: Pick<CompensationDeps, 'store' | 'dlq'>,
+    private readonly log: LogFn,
+  ) {
+    this.kafka = new Kafka({ clientId: 'node-svc-compensation', brokers });
+  }
+
+  /** Connect + subscribe + run — lazy/retry (conventions/09 rule 1): broker
+   *  chưa lên HOẶC topic chưa auto-create xong = warn + retry, KHÔNG crash.
+   *  Trả promise chạy dài; caller void (+ .catch phòng thủ ở call site). */
+  async start(): Promise<void> {
+    const consumer = this.kafka.consumer({ groupId: COMPENSATION_GROUP });
+    while (!this.stopped) {
+      try {
+        await consumer.connect();
+        break;
+      } catch (err) {
+        this.log('warn', 'kafka consumer connect failed — retry', {
+          err: err instanceof Error ? err.message : String(err),
+        });
+        await new Promise<void>((r) => setTimeout(r, CONNECT_RETRY_MS));
+      }
+    }
+    if (this.stopped) return;
+    this.consumer = consumer;
+
+    // subscribe + run PHỦ retry riêng: demo dùng auto-create topic — subscribe
+    // trước khi topic `task-events` được broker tạo xong → kafkajs ném
+    // UNKNOWN_TOPIC_OR_PARTITION (retriable) RA NGOÀI subscribe() thay vì tự
+    // retry (CI run 38365465140: unhandled rejection crash process → readyz
+    // chết). Vòng lặp này biến nó thành warn + retry — không crash.
+    while (!this.stopped) {
+      try {
+        await consumer.subscribe({ topic: 'task-events', fromBeginning: true });
+        // auto.offset.reset: earliest tương đương fromBeginning cho group mới —
+        // fixture demo đọc lại từ đầu, idempotency (conditional guard) lo duplicates.
+        await consumer.run({
+          autoCommit: false, // manual commit SAU khi DB op xong (conventions/09 rule 5)
+          eachMessage: async ({ topic, partition, message }) => {
+            await handleMessage(message.value?.toString() ?? '', {
+              ...this.deps,
+              commit: async () => {
+                await consumer.commitOffsets([
+                  { topic, partition, offset: (BigInt(message.offset) + 1n).toString() },
+                ]);
+              },
+              log: this.log,
+            });
+          },
+        });
+        break; // run trả về bình thường (stopped/disconnect)
+      } catch (err) {
+        this.log('warn', 'kafka consumer subscribe/run failed — retry', {
+          err: err instanceof Error ? err.message : String(err),
+        });
+        await new Promise<void>((r) => setTimeout(r, CONNECT_RETRY_MS));
+      }
+    }
+  }
+
+  async stop(): Promise<void> {
+    this.stopped = true;
+    if (this.consumer) {
+      await this.consumer.disconnect();
+      this.consumer = null;
+    }
+  }
+}

package/stack-template/services/node-svc/src/db/client.ts

@@ -0,0 +1,23 @@
+// client.ts — pg Pool + drizzle instance (DATABASE_URL, role node_svc).
+import { drizzle } from 'drizzle-orm/node-postgres';
+import { Pool } from 'pg';
+import type { NodePgDatabase } from 'drizzle-orm/node-postgres';
+
+export interface Db {
+  pool: Pool;
+  db: NodePgDatabase;
+}
+
+export function createDb(databaseUrl: string): Db {
+  const pool = new Pool({
+    connectionString: databaseUrl,
+    max: 10,
+    // fail nhanh thay vì treo boot khi postgres chưa lên
+    connectionTimeoutMillis: 5000,
+  });
+  return { pool, db: drizzle(pool) };
+}
+
+export async function closeDb(db: Db): Promise<void> {
+  await db.pool.end();
+}

package/stack-template/services/node-svc/src/db/migrate.ts

@@ -0,0 +1,63 @@
+// migrate.ts — SQL-file migration runner.
+//
+// VÌ KHÔNG DÙNG drizzle migrator: PgDialect.migrate luôn phát
+// `CREATE SCHEMA IF NOT EXISTS "<migrationsSchema>"` — statement này cần
+// CREATE trên DATABASE (node_svc chỉ có CREATE trên schema tasks, xem
+// platform/postgres/init/01-init.sh) → permission denied lúc boot (CI run
+// 38229973307). Runner này: thử CREATE SCHEMA, chấp nhận khi schema đã tồn
+// tại (tạo bởi init script); tracking trong tasks.migrations_history (role
+// node_svc sở hữu); statement parse đúng marker của drizzle-kit nên vẫn
+// generate migration bằng `pnpm exec drizzle-kit generate` như thường.
+import { readdirSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+import { sql } from 'drizzle-orm';
+import type { NodePgDatabase } from 'drizzle-orm/node-postgres';
+
+export async function runMigrations(db: NodePgDatabase, migrationsFolder: string): Promise<string[]> {
+  await db.execute(
+    sql`create table if not exists tasks.migrations_history (name text primary key, applied_at timestamptz not null default now())`,
+  );
+  const applied = new Set<string>(
+    (await db.execute(sql`select name from tasks.migrations_history`)).rows.map(
+      (r) => r.name as string,
+    ),
+  );
+
+  const files = readdirSync(migrationsFolder)
+    .filter((f) => f.endsWith('.sql'))
+    .sort();
+  const ran: string[] = [];
+
+  for (const file of files) {
+    if (applied.has(file)) continue;
+    const content = readFileSync(path.join(migrationsFolder, file), 'utf8');
+    const statements = content
+      .split('--> statement-breakpoint')
+      .map((s) => s.trim())
+      .filter(Boolean);
+
+    for (const stmt of statements) {
+      if (/^create schema if not exists/i.test(stmt)) {
+        // Schema do init script tạo trước (compose fresh volume). Role migration
+        // không có CREATE trên database → statement này permission denied dù
+        // IF NOT EXISTS (PG check privilege trước existence notice). Thử chạy
+        // (cho setup mới); schema đã tồn tại → chấp nhận, nếu chưa tồn tại
+        // thật sự thì rethrow (không nuốt lỗi).
+        try {
+          await db.execute(sql.raw(stmt));
+        } catch (err) {
+          const check = await db.execute(
+            sql`select to_regnamespace('tasks') is not null as ok`,
+          );
+          if (!check.rows[0]?.ok) throw err;
+        }
+        continue;
+      }
+      await db.execute(sql.raw(stmt));
+    }
+
+    await db.execute(sql`insert into tasks.migrations_history (name) values (${file})`);
+    ran.push(file);
+  }
+  return ran;
+}