create-wakii-stack 0.0.0-stage → 0.1.0

package/stack-template/services/node-svc/src/outbox-relay.ts

@@ -0,0 +1,182 @@
+// outbox-relay.ts — relay worker poll outbox → publish topic `task-events`
+// (conventions/09 rule 2 + task-events.md). KHÔNG publish trong request path:
+// mutation chỉ ghi outbox trong tx (repo.drizzle.ts), relay publish SAU —
+// publish TRƯỚC mark published_at → crash giữa chừng = publish lại (duplicate)
+// → at-least-once, consumer dedupe bằng envelope id. Message key = payload.taskId
+// (thứ tự per-task trong 1 partition — task-events.md). Purge row published cũ.
+import { inArray, isNull, lt } from 'drizzle-orm';
+import { Kafka, type Producer } from 'kafkajs';
+import type { NodePgDatabase } from 'drizzle-orm/node-postgres';
+import { outbox, type OutboxRow } from './db/schema.js';
+import type { LogFn } from './types/log.js';
+
+export const TASK_EVENTS_TOPIC = 'task-events';
+export const RELAY_BATCH = 100;
+export const PURGE_AFTER_MS = 7 * 24 * 60 * 60 * 1000; // published cũ > 7 ngày
+export const PURGE_EVERY_TICKS = 240; // ~2 phút ở poll 500ms
+
+/** Envelope đúng golden fixture format (contracts/events/fixtures/*.json —
+ *  task-events.md là nguồn sự thật; test 2 đầu load chung fixture). */
+export interface EventEnvelope {
+  schemaVersion: 1;
+  id: string;
+  type: string;
+  occurredAt: string; // RFC3339 UTC — thời điểm mutation (createdAt của row outbox)
+  payload: Record<string, unknown>;
+}
+
+export function toEnvelope(row: OutboxRow): EventEnvelope {
+  return {
+    schemaVersion: 1,
+    id: row.id,
+    type: row.type,
+    occurredAt: row.createdAt.toISOString(),
+    payload: row.payload as Record<string, unknown>, // jsonb select type = unknown
+  };
+}
+
+export interface OutboxMessage {
+  key: string | null; // = payload.taskId (task-events.md)
+  value: string; // JSON envelope
+}
+
+function messageKey(envelope: EventEnvelope): string | null {
+  const taskId = envelope.payload.taskId;
+  return typeof taskId === 'string' ? taskId : null;
+}
+
+/** Trừu tượng publish cho unit test (fake producer). */
+export interface EventPublisher {
+  send(topic: string, messages: OutboxMessage[]): Promise<void>;
+}
+
+/** Trừu tượng đọc/ghi outbox cho unit test (fake store). */
+export interface OutboxStore {
+  findUnpublished(limit: number): Promise<OutboxRow[]>;
+  markPublished(ids: string[]): Promise<void>;
+  purgePublished(olderThan: Date): Promise<number>;
+}
+
+export class DrizzleOutboxStore implements OutboxStore {
+  constructor(private readonly db: NodePgDatabase) {}
+
+  async findUnpublished(limit: number): Promise<OutboxRow[]> {
+    return this.db
+      .select()
+      .from(outbox)
+      .where(isNull(outbox.publishedAt))
+      .orderBy(outbox.createdAt)
+      .limit(limit);
+  }
+
+  async markPublished(ids: string[]): Promise<void> {
+    await this.db
+      .update(outbox)
+      .set({ publishedAt: new Date() })
+      .where(inArray(outbox.id, ids));
+  }
+
+  async purgePublished(olderThan: Date): Promise<number> {
+    const purged = await this.db
+      .delete(outbox)
+      .where(lt(outbox.publishedAt, olderThan))
+      .returning();
+    return purged.length;
+  }
+}
+
+/** kafkajs producer — lazy-connect (conventions/09 rule 1): connect fail =
+ *  throw → relay warn + retry tick kế (KHÔNG crash, KHÔNG vào readyz). */
+export class KafkaEventPublisher implements EventPublisher {
+  private producer: Producer | null = null;
+  private readonly kafka: Kafka;
+
+  constructor(
+    brokers: string[],
+    private readonly log: LogFn,
+  ) {
+    this.kafka = new Kafka({ clientId: 'node-svc-outbox', brokers });
+  }
+
+  async send(topic: string, messages: OutboxMessage[]): Promise<void> {
+    if (!this.producer) {
+      this.producer = this.kafka.producer();
+      await this.producer.connect(); // fail → throw → relay retry tick sau
+      this.log('info', 'kafka producer connected');
+    }
+    try {
+      await this.producer.send({ topic, messages });
+    } catch (err) {
+      // send fail sau connect (broker sập giữa chừng) — drop producer để tick
+      // sau connect lại từ đầu thay vì tái dụng connection chết (review NV-fix)
+      this.producer = null;
+      throw err;
+    }
+  }
+
+  async disconnect(): Promise<void> {
+    if (this.producer) {
+      await this.producer.disconnect();
+      this.producer = null;
+    }
+  }
+}
+
+export class OutboxRelay {
+  private timer: NodeJS.Timeout | undefined;
+  private ticks = 0;
+  private running = false; // in-flight guard — tick >interval không chồng nhau
+  private readonly purgeEveryTicks: number;
+  private readonly purgeAfterMs: number;
+
+  constructor(
+    private readonly store: OutboxStore,
+    private readonly publisher: EventPublisher,
+    private readonly log: LogFn,
+    private readonly intervalMs = 500, // spec: poll ~500ms
+    opts: { purgeEveryTicks?: number; purgeAfterMs?: number } = {},
+  ) {
+    this.purgeEveryTicks = opts.purgeEveryTicks ?? PURGE_EVERY_TICKS;
+    this.purgeAfterMs = opts.purgeAfterMs ?? PURGE_AFTER_MS;
+  }
+
+  start(): void {
+    this.timer = setInterval(() => void this.tick(), this.intervalMs);
+  }
+
+  stop(): void {
+    if (this.timer) clearInterval(this.timer);
+  }
+
+  /** 1 chu kỳ poll — public để unit test gọi trực tiếp (không đợi interval). */
+  async tick(): Promise<void> {
+    if (this.running) return; // tick trước chưa xong — bỏ qua, rows còn unpublished
+    this.running = true;
+    try {
+      this.ticks++;
+      const rows = await this.store.findUnpublished(RELAY_BATCH);
+      if (rows.length > 0) {
+        await this.publisher.send(
+          TASK_EVENTS_TOPIC,
+          rows.map((row) => {
+            const envelope = toEnvelope(row);
+            return { key: messageKey(envelope), value: JSON.stringify(envelope) };
+          }),
+        );
+        // publish TRƯỚC mark — crash giữa chừng = re-publish (at-least-once,
+        // consumer dedupe). Mark SAU publish KHÔNG được fail ngược dòng.
+        await this.store.markPublished(rows.map((row) => row.id));
+      }
+      if (this.ticks % this.purgeEveryTicks === 0) {
+        const purged = await this.store.purgePublished(new Date(Date.now() - this.purgeAfterMs));
+        if (purged > 0) this.log('info', 'outbox purged', { purged });
+      }
+    } catch (err) {
+      this.log('warn', 'outbox relay tick failed — sẽ retry', {
+        err: err instanceof Error ? err.message : String(err),
+      });
+    } finally {
+      this.running = false;
+    }
+  }
+}

package/stack-template/services/node-svc/src/plugins/auth.ts

@@ -0,0 +1,76 @@
+// auth.ts — JWT guard (token-contract.md §4 lớp 2): service TỰ verify
+// signature (HS256 + JWT_SECRET) + expiry + iss, KHÔNG tin gateway.
+// healthz/readyz/docs được exempt. Fail → 401 envelope UNAUTHORIZED.
+import type { FastifyReply, FastifyRequest } from 'fastify';
+import jwt from 'jsonwebtoken';
+
+export const JWT_ISSUER = 'auth-mock';
+
+export interface JwtUser {
+  sub: string;
+  email: string;
+  roles: string[];
+}
+
+declare module 'fastify' {
+  interface FastifyRequest {
+    user?: JwtUser;
+    bearerToken?: string;
+  }
+}
+
+export function verifyToken(
+  authorization: string | undefined,
+  jwtSecret: string,
+): { ok: true; user: JwtUser; token: string } | { ok: false; reason: string } {
+  if (!authorization || !authorization.startsWith('Bearer ')) {
+    return { ok: false, reason: 'missing bearer token' };
+  }
+  const token = authorization.slice('Bearer '.length).trim();
+  try {
+    const payload = jwt.verify(token, jwtSecret, {
+      algorithms: ['HS256'],
+      issuer: JWT_ISSUER,
+    });
+    if (typeof payload === 'string' || typeof payload.sub !== 'string') {
+      return { ok: false, reason: 'invalid claims' };
+    }
+    return {
+      ok: true,
+      token,
+      user: {
+        sub: payload.sub,
+        email: typeof payload.email === 'string' ? payload.email : '',
+        roles: Array.isArray(payload.roles) ? (payload.roles as string[]) : [],
+      },
+    };
+  } catch (err) {
+    return { ok: false, reason: err instanceof Error ? err.message : 'verify failed' };
+  }
+}
+
+/** onRequest hook cho business routes — mount trong plugin có prefix /api/tasks. */
+export function authGuard(jwtSecret: string, exemptExact: string[] = ['/healthz', '/readyz']) {
+  return (request: FastifyRequest, reply: FastifyReply, done: () => void): void => {
+    const path = request.routeOptions?.url ?? '';
+    if (exemptExact.some((p) => path === p || path.startsWith('/docs'))) {
+      done();
+      return;
+    }
+    const result = verifyToken(request.headers.authorization, jwtSecret);
+    if (!result.ok) {
+      reply.status(401).send({
+        error: {
+          code: 'UNAUTHORIZED',
+          message: 'Missing or invalid JWT',
+          requestId: request.id,
+          details: null,
+        },
+      });
+      return;
+    }
+    request.user = result.user;
+    request.bearerToken = result.token;
+    done();
+  };
+}

package/stack-template/services/node-svc/src/repo.drizzle.test.ts

@@ -0,0 +1,182 @@
+// repo.drizzle.test.ts — transactional outbox wiring của DrizzleTaskRepo (SF-2
+// FI-79). Không postgres local → mock NodePgDatabase: transaction() chạy callback
+// trên working-copy, COMMIT chỉ khi callback thành công; throw (seam fail ở
+// bước outbox insert) = ROLLBACK — task + outbox CÙNG biến mất. Rollback thật
+// của postgres được chứng minh ở CI kafka boot-smoke + e2e (Rule 0 evidence).
+import { describe, expect, it } from 'vitest';
+import type { NodePgDatabase } from 'drizzle-orm/node-postgres';
+import { outbox, tasks } from './db/schema.js';
+import { DrizzleTaskRepo } from './repo.drizzle.js';
+
+interface RowRec {
+  table: unknown;
+  row: Record<string, unknown>;
+}
+
+/** Mock db đủ bề mặt repo dùng: transaction/insert().values().returning()/update/delete. */
+class MockDb {
+  committed: RowRec[] = [];
+  private pending: RowRec[] = [];
+  failOnOutboxInsert = false;
+  transactionCalls = 0;
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  updateResult: any[] = []; // rows trả về cho update().returning()
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  deleteResult: any[] = []; // rows trả về cho delete().returning()
+
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  async transaction(cb: (tx: any) => Promise<any>): Promise<any> {
+    this.transactionCalls++;
+    this.pending = this.committed.map((rec) => ({ ...rec }));
+    const tx = {
+      insert: (table: unknown) => ({
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        values: (v: any) => {
+          const rows = (Array.isArray(v) ? v : [v]).map((r) => ({
+            createdAt: new Date(),
+            updatedAt: new Date(),
+            ...r,
+          }));
+          const persist = async () => {
+            // SEAM: fail giữa 2 step (task đã "ghi" working-copy, outbox chưa)
+            if (table === outbox && this.failOnOutboxInsert) {
+              throw new Error('seam: outbox insert failed');
+            }
+            const result = rows.map((r) => ({ ...r }));
+            for (const r of result) this.pending.push({ table, row: r });
+            return result;
+          };
+          const builder = { returning: persist } as { returning: typeof persist; then?: unknown };
+          // insert().values() KHÔNG .returning() vẫn await được (drizzle thenable)
+          builder.then = (
+            resolve: (v: unknown) => unknown,
+            reject: (e: unknown) => unknown,
+          ) => persist().then(resolve, reject);
+          return builder;
+        },
+      }),
+      update: (_table: unknown) => ({
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        set: (_v: any) => ({
+          where: (_cond: unknown) => ({
+            returning: async () => this.updateResult.map((r) => ({ ...r })),
+          }),
+        }),
+      }),
+      delete: (_table: unknown) => ({
+        where: (_cond: unknown) => ({
+          returning: async () => this.deleteResult.map((r) => ({ ...r })),
+        }),
+      }),
+    };
+    try {
+      const result = await cb(tx);
+      this.committed = this.pending; // COMMIT — chỉ khi toàn bộ callback xong
+      return result;
+    } catch (err) {
+      // ROLLBACK — pending bị vứt, committed nguyên vẹn
+      throw err;
+    } finally {
+      this.pending = [];
+    }
+  }
+}
+
+function makeRepo(db: MockDb): DrizzleTaskRepo {
+  return new DrizzleTaskRepo(db as unknown as NodePgDatabase);
+}
+
+const EVENT = { type: 'task.created' as const, payload: { taskId: 't-1', userId: 'u-1', title: 'x', status: 'todo' } };
+
+describe('DrizzleTaskRepo — mutation + outbox cùng 1 tx (conventions/09 rule 2)', () => {
+  it('create: task + outbox ghi trong CÙNG 1 transaction callback', async () => {
+    const db = new MockDb();
+    const repo = makeRepo(db);
+    const task = await repo.create(
+      { id: 't-1', title: 'x', createdBy: 'u-1' },
+      [EVENT],
+    );
+    expect(task.id).toBe('t-1');
+    expect(db.transactionCalls).toBe(1); // 1 tx duy nhất cho cả 2 op
+    expect(db.committed.filter((r) => r.table === tasks)).toHaveLength(1);
+    expect(db.committed.filter((r) => r.table === outbox)).toHaveLength(1);
+    const outboxRow = db.committed.find((r) => r.table === outbox)!.row;
+    expect(outboxRow.type).toBe('task.created');
+    expect(typeof outboxRow.id).toBe('string'); // envelope id do repo sinh
+  });
+
+  it('n events → n outbox row, mỗi event 1 envelope id riêng (task-events.md)', async () => {
+    const db = new MockDb();
+    const repo = makeRepo(db);
+    await repo.create(
+      { id: 't-1', title: 'x', createdBy: 'u-1' },
+      [EVENT, { type: 'task.updated', payload: { taskId: 't-1', userId: 'u-1' } }],
+    );
+    const outboxRows = db.committed.filter((r) => r.table === outbox);
+    expect(outboxRows).toHaveLength(2);
+    expect(outboxRows[0].row.id).not.toBe(outboxRows[1].row.id);
+  });
+
+  it('SEAM ROLLBACK: outbox insert fail giữa 2 step → task + outbox cùng biến mất', async () => {
+    const db = new MockDb();
+    db.failOnOutboxInsert = true;
+    const repo = makeRepo(db);
+    await expect(repo.create({ id: 't-1', title: 'x', createdBy: 'u-1' }, [EVENT])).rejects.toThrow(
+      'seam',
+    );
+    // rollback: committed rỗng — KHÔNG còn task row lẫn outbox row (acceptance)
+    expect(db.committed).toHaveLength(0);
+  });
+
+  it('REGRESSION (review P0): update miss 0 row (404) → KHÔNG emit outbox event', async () => {
+    const db = new MockDb();
+    db.updateResult = []; // 0 row match — task không tồn tại
+    const repo = makeRepo(db);
+    const result = await repo.update('missing', { status: 'done' }, [
+      { type: 'task.updated', payload: { taskId: 'missing', userId: 'u-1', status: 'done' } },
+    ]);
+    expect(result).toBeNull();
+    expect(db.committed.filter((r) => r.table === outbox)).toHaveLength(0); // không phantom event
+  });
+
+  it('update hit → task + outbox emit trong cùng tx', async () => {
+    const db = new MockDb();
+    db.updateResult = [
+      {
+        id: 't-1',
+        title: 'x',
+        description: null,
+        status: 'done',
+        assigneeId: null,
+        createdBy: 'u-1',
+        createdAt: new Date(),
+        updatedAt: new Date(),
+      },
+    ];
+    const repo = makeRepo(db);
+    const task = await repo.update('t-1', { status: 'done' }, [
+      { type: 'task.updated', payload: { taskId: 't-1', userId: 'u-1', status: 'done' } },
+    ]);
+    expect(task?.status).toBe('done');
+    expect(db.transactionCalls).toBe(1);
+    expect(db.committed.filter((r) => r.table === outbox)).toHaveLength(1);
+  });
+
+  it('REGRESSION (review P0): delete miss 0 row → KHÔNG emit; delete hit → emit', async () => {
+    const db = new MockDb();
+    db.deleteResult = [];
+    const repo = makeRepo(db);
+    const miss = await repo.remove('missing', [
+      { type: 'task.deleted', payload: { taskId: 'missing', userId: 'u-1' } },
+    ]);
+    expect(miss).toBe(false);
+    expect(db.committed.filter((r) => r.table === outbox)).toHaveLength(0);
+
+    db.deleteResult = [{ id: 't-1' }];
+    const hit = await repo.remove('t-1', [
+      { type: 'task.deleted', payload: { taskId: 't-1', userId: 'u-1' } },
+    ]);
+    expect(hit).toBe(true);
+    expect(db.committed.filter((r) => r.table === outbox)).toHaveLength(1);
+  });
+});

package/stack-template/services/node-svc/src/repo.drizzle.ts

@@ -0,0 +1,158 @@
+// repo.drizzle.ts — drizzle-orm implementation của TaskRepo (schema `tasks`,
+// canonical DDL contracts/db/tasks-schema.sql). Bảng do migration tạo (role
+// node_svc, search_path=tasks set bởi 01-init.sh).
+//
+// SF-2 (FI-79): mutation + INSERT outbox trong CÙNG 1 tx (db.transaction —
+// conventions/09 rule 2). Thứ tự trong tx: task mutation TRƯỚC, outbox SAU —
+// fail ở bước nào cũng rollback cả 2 (test: repo.drizzle.test.ts seam).
+import { and, count, desc, eq, ne, sql } from 'drizzle-orm';
+import type { NodePgDatabase } from 'drizzle-orm/node-postgres';
+import { outbox, tasks } from './db/schema.js';
+import type {
+  ListFilter,
+  OutboxEventInput,
+  Task,
+  TaskCreate,
+  TaskPatch,
+  TaskRepo,
+  TaskStatusExtended,
+} from './repo.js';
+
+type Row = typeof tasks.$inferSelect;
+type Tx = Parameters<Parameters<NodePgDatabase['transaction']>[0]>[0];
+
+function toTask(row: Row): Task {
+  return {
+    id: row.id,
+    title: row.title,
+    description: row.description,
+    status: row.status as TaskStatusExtended,
+    assigneeId: row.assigneeId,
+    createdBy: row.createdBy,
+    createdAt: row.createdAt.toISOString(),
+    updatedAt: row.updatedAt.toISOString(),
+  };
+}
+
+export class DrizzleTaskRepo implements TaskRepo {
+  constructor(private readonly db: NodePgDatabase) {}
+
+  async ping(): Promise<void> {
+    await this.db.execute(sql`select 1`);
+  }
+
+  async list(filter: ListFilter): Promise<{ items: Task[]; total: number }> {
+    const conditions = [
+      filter.status ? eq(tasks.status, filter.status) : undefined,
+      filter.assigneeId ? eq(tasks.assigneeId, filter.assigneeId) : undefined,
+    ].filter(Boolean);
+
+    const rows = await this.db
+      .select()
+      .from(tasks)
+      .where(conditions.length > 0 ? and(...conditions) : undefined)
+      .orderBy(desc(tasks.createdAt))
+      .limit(filter.limit)
+      .offset(filter.offset);
+
+    const [{ value: total }] = await this.db
+      .select({ value: count() })
+      .from(tasks)
+      .where(conditions.length > 0 ? and(...conditions) : undefined);
+
+    return { items: rows.map(toTask), total };
+  }
+
+  async getById(id: string): Promise<Task | null> {
+    const [row] = await this.db.select().from(tasks).where(eq(tasks.id, id)).limit(1);
+    return row ? toTask(row) : null;
+  }
+
+  async create(input: TaskCreate, events: OutboxEventInput[]): Promise<Task> {
+    return this.mutateWithOutbox(events, async (tx, emit) => {
+      const [row] = await tx
+        .insert(tasks)
+        .values({
+          id: input.id ?? crypto.randomUUID(),
+          title: input.title,
+          description: input.description ?? null,
+          status: 'todo',
+          assigneeId: input.assigneeId ?? null,
+          createdBy: input.createdBy,
+        })
+        .returning();
+      await emit(); // create luôn affected ≥1 — insert thành công là có row
+      return toTask(row);
+    });
+  }
+
+  async update(id: string, patch: TaskPatch, events: OutboxEventInput[]): Promise<Task | null> {
+    return this.mutateWithOutbox(events, async (tx, emit) => {
+      const values: Partial<Row> = { updatedAt: new Date() };
+      if (patch.title !== undefined) values.title = patch.title;
+      if (patch.description !== undefined) values.description = patch.description;
+      if (patch.status !== undefined) values.status = patch.status;
+      if (patch.assigneeId !== undefined) values.assigneeId = patch.assigneeId;
+
+      const [row] = await tx
+        .update(tasks)
+        .set(values)
+        .where(eq(tasks.id, id))
+        .returning();
+      // Gate theo row-affected: 0 row (404) KHÔNG emit event — tránh phantom
+      // event cho task không tồn tại (review P0 FI-79).
+      if (row) await emit();
+      return row ? toTask(row) : null;
+    });
+  }
+
+  async remove(id: string, events: OutboxEventInput[]): Promise<boolean> {
+    return this.mutateWithOutbox(events, async (tx, emit) => {
+      const deleted = await tx
+        .delete(tasks)
+        .where(eq(tasks.id, id))
+        .returning();
+      if (deleted.length > 0) await emit(); // 0 row (404) → không emit
+      return deleted.length > 0;
+    });
+  }
+
+  async markAssignmentFailed(taskId: string, assigneeId: string): Promise<boolean> {
+    // CONDITIONAL guard (ADR-0008 — bắt buộc): chỉ đổi khi assignee khớp event
+    // (chống stale compensation — event cũ cho assignee cũ phải bỏ qua) VÀ
+    // chưa ở 'assignment_failed' (idempotent — event lặp match 0 row).
+    const updated = await this.db
+      .update(tasks)
+      .set({ status: 'assignment_failed', updatedAt: new Date() })
+      .where(
+        and(eq(tasks.id, taskId), eq(tasks.assigneeId, assigneeId), ne(tasks.status, 'assignment_failed')),
+      )
+      .returning();
+    return updated.length > 0;
+  }
+
+  /**
+   * mutation + outbox trong CÙNG tx; envelope id sinh tại đây, MỖI event 1 id.
+   * `emit` do mutation tự gọi SAU khi biết row-affected — 0 row (PATCH/DELETE
+   * trúng 404) KHÔNG emit → không có phantom event cho task không tồn tại.
+   */
+  private mutateWithOutbox<T>(
+    events: OutboxEventInput[],
+    mutate: (tx: Tx, emit: () => Promise<void>) => Promise<T>,
+  ): Promise<T> {
+    return this.db.transaction(async (tx) => {
+      const emit = async (): Promise<void> => {
+        if (events.length > 0) {
+          await tx.insert(outbox).values(
+            events.map((event) => ({
+              id: crypto.randomUUID(),
+              type: event.type,
+              payload: event.payload,
+            })),
+          );
+        }
+      };
+      return mutate(tx, emit);
+    });
+  }
+}

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

@@ -0,0 +1,73 @@
+// repo.ts — repository interface: route layer phụ thuộc interface này, KHÔNG
+// phụ thuộc drizzle trực tiếp → unit test inject in-memory fake (không postgres
+// local), CI boot-smoke bấm DrizzleTaskRepo thật (đó là chỗ SQL được verify).
+//
+// SF-2 (FI-79) — transactional outbox (ADR-0008, conventions/09 rule 2): mọi
+// mutation nhận outbox op (`events`) và ghi task + outbox trong CÙNG 1 tx.
+// Envelope `id` (UUIDv4) + `occurredAt` do REPO sinh từng event (task-events.md:
+// producer sinh MỖI event — consumer dùng id làm khóa idempotency, KHÔNG taskId).
+// Route build `events` theo event matrix PRESENCE-BASED (body có gì bắn nấy —
+// ADR-0008 ghi value-compare là path production, KHÔNG value-compare ở đây).
+export type TaskStatus = 'todo' | 'in_progress' | 'done';
+// READ-ONLY mở rộng: `assignment_failed` chỉ compensation consumer ghi — PATCH
+// body không nhận (tasks.yaml: TaskStatus writable 3 / TaskStatusExtended 4).
+export type TaskStatusExtended = TaskStatus | 'assignment_failed';
+
+export type TaskEventType = 'task.created' | 'task.updated' | 'task.assigned' | 'task.deleted';
+
+/** Outbox op do route build — envelope id/occurredAt do repo điền lúc ghi. */
+export interface OutboxEventInput {
+  type: TaskEventType;
+  payload: Record<string, unknown>;
+}
+
+export interface Task {
+  id: string;
+  title: string;
+  description: string | null;
+  status: TaskStatusExtended;
+  assigneeId: string | null;
+  createdBy: string;
+  createdAt: string; // ISO 8601 UTC
+  updatedAt: string;
+}
+
+export interface ListFilter {
+  status?: TaskStatus; // query param — writable 3 giá trị (tasks.yaml)
+  assigneeId?: string;
+  limit: number; // 1..100
+  offset: number; // >=0
+}
+
+export interface TaskCreate {
+  title: string;
+  description?: string | null;
+  assigneeId?: string | null;
+  createdBy: string;
+  /** Route sinh TRƯỚC khi create (payload event cần taskId cùng tx). Repo tự
+   *  sinh nếu bỏ qua — DDL: id app-generated uuid v4, không gen_random_uuid. */
+  id?: string;
+}
+
+export interface TaskPatch {
+  title?: string;
+  description?: string | null;
+  status?: TaskStatus;
+  assigneeId?: string | null;
+}
+
+export interface TaskRepo {
+  ping(): Promise<void>; // readyz — SELECT 1 thật
+  list(filter: ListFilter): Promise<{ items: Task[]; total: number }>;
+  getById(id: string): Promise<Task | null>;
+  /** mutation + INSERT outbox trong CÙNG 1 tx — events rỗng = không bắn event. */
+  create(input: TaskCreate, events: OutboxEventInput[]): Promise<Task>;
+  update(id: string, patch: TaskPatch, events: OutboxEventInput[]): Promise<Task | null>;
+  remove(id: string, events: OutboxEventInput[]): Promise<boolean>;
+  /**
+   * Compensation consumer (saga — ADR-0008): conditional UPDATE chống stale
+   * compensation — chỉ đổi khi assignee KHỚP event VÀ chưa ở trạng thái đích.
+   * Trả true khi UPDATE khớp ≥1 row (idempotent: event lặp → lần 2 match 0).
+   */
+  markAssignmentFailed(taskId: string, assigneeId: string): Promise<boolean>;
+}