@gaonjs/async 0.2.0 → 0.2.2

package/dist/schedule.js

@@ -0,0 +1,143 @@
+// @gaonjs/async · 스케줄러 (§7 M7 · line 838~856)
+//
+// 반복 작업은 `domain/schedule.ts` 한 파일에 선언한다. 크론을 몰라도 되는
+// 자연스러운 API 를 기본으로, 크론식도 받는다. 실행 대상은 **항상 잡**이다
+// (인라인 함수 금지 — 실패·재시도·관측을 잡 레이어로 일원화, line 853).
+//
+//   export default schedule((s) => {
+//     s.every('10m', CleanupExpiredSessions)
+//     s.daily.at('04:00', SendDailyDigest)
+//     s.cron('0 9 * * 1', SendWeeklyReport)
+//   })
+//
+// 다중 인스턴스에서 같은 스케줄이 두 번 발행되지 않도록, NATS KV 리스로
+// 리더를 선출해 리더 인스턴스만 틱을 발행한다(line 855 · leaseLeader 재사용).
+// 발행 = 대상 잡의 `.later()` 큐잉이다.
+import { leaseLeader } from './lease.js';
+import { parseCron } from './cron.js';
+import { parseDuration } from './duration.js';
+/** 스케줄을 선언한다. 콜백에서 s.every/daily.at/cron 으로 항목을 등록한다. */
+export function schedule(build) {
+    const entries = [];
+    const builder = {
+        every(interval, job) {
+            const intervalMs = parseDuration(interval);
+            if (intervalMs <= 0)
+                throw new Error(`[@gaonjs/async] every 간격은 0보다 커야 합니다: ${interval}`);
+            entries.push({ kind: 'every', intervalMs, job, label: `every ${interval} → ${job.name}` });
+        },
+        daily: {
+            at(hhmm, job) {
+                const m = /^(\d{1,2}):(\d{2})$/.exec(hhmm.trim());
+                if (!m) {
+                    throw new Error(`[@gaonjs/async] daily.at 시각 형식이 잘못됐습니다: '${hhmm}'\n` + `→ 'HH:MM' 로 쓰세요 — 예: '04:00'.`);
+                }
+                const hh = Number(m[1]);
+                const mm = Number(m[2]);
+                if (hh > 23 || mm > 59) {
+                    throw new Error(`[@gaonjs/async] daily.at 시각이 범위를 벗어났습니다: '${hhmm}'`);
+                }
+                entries.push({
+                    kind: 'cron',
+                    matcher: parseCron(`${mm} ${hh} * * *`),
+                    job,
+                    label: `daily ${hhmm} → ${job.name}`,
+                });
+            },
+        },
+        cron(expr, job) {
+            entries.push({ kind: 'cron', matcher: parseCron(expr), job, label: `cron '${expr}' → ${job.name}` });
+        },
+    };
+    build(builder);
+    return { entries };
+}
+const DEFAULT_TICK_MS = 1000;
+/**
+ * 스케줄러를 시작한다. 리더로 선출된 인스턴스만 틱을 발행한다. 리더십을
+ * 잃으면 발행을 멈추고, 되찾으면 재개한다(중복 발행 없음).
+ */
+export async function runScheduler(opts) {
+    const tickMs = opts.tickMs ?? DEFAULT_TICK_MS;
+    const nowFn = opts.now ?? (() => Date.now());
+    const emit = (e) => opts.onEvent?.(e);
+    // every 항목의 다음 발행 시각, cron 항목의 마지막 발행 분(중복 방지).
+    const nextEvery = new Map();
+    const lastCronMinute = new Map();
+    let leading = false;
+    let timer;
+    let stopped = false;
+    const resetSchedules = () => {
+        const now = nowFn();
+        nextEvery.clear();
+        lastCronMinute.clear();
+        for (const e of opts.def.entries) {
+            if (e.kind === 'every')
+                nextEvery.set(e, now + e.intervalMs);
+        }
+    };
+    const fire = async (job, label) => {
+        try {
+            await job.later();
+            emit({ kind: 'fired', job: job.name, label });
+        }
+        catch (err) {
+            emit({ kind: 'error', error: err instanceof Error ? err.message : String(err) });
+        }
+    };
+    const tick = async () => {
+        if (!leading || stopped)
+            return;
+        const now = nowFn();
+        const minute = Math.floor(now / 60000);
+        for (const e of opts.def.entries) {
+            if (e.kind === 'every') {
+                const due = nextEvery.get(e) ?? now + e.intervalMs;
+                if (now >= due) {
+                    nextEvery.set(e, due + e.intervalMs);
+                    await fire(e.job, e.label);
+                }
+            }
+            else {
+                // 분 경계 한 번만 발행: 이 분에 아직 안 쐈고 매처가 맞으면.
+                if (lastCronMinute.get(e) !== minute && e.matcher.matches(new Date(now))) {
+                    lastCronMinute.set(e, minute);
+                    await fire(e.job, e.label);
+                }
+            }
+        }
+    };
+    const loop = () => {
+        void tick().finally(() => {
+            if (!stopped)
+                timer = setTimeout(loop, tickMs);
+        });
+    };
+    const lease = await leaseLeader({
+        nats: opts.nats,
+        key: 'scheduler.leader',
+        id: opts.id,
+        ttlMs: opts.ttlMs,
+        onElected: () => {
+            leading = true;
+            resetSchedules();
+            emit({ kind: 'leader', leader: true });
+        },
+        onRevoked: () => {
+            leading = false;
+            emit({ kind: 'leader', leader: false });
+        },
+    });
+    loop();
+    return {
+        get isLeader() {
+            return lease.isLeader;
+        },
+        async stop() {
+            stopped = true;
+            if (timer)
+                clearTimeout(timer);
+            await lease.stop();
+        },
+    };
+}

package/dist/streams.d.ts

@@ -0,0 +1,37 @@
+import type { GaonNats } from './nats.js';
+export declare const JOBS_STREAM = "GAON_JOBS";
+export declare const DLQ_STREAM = "GAON_JOBS_DLQ";
+export declare const EVENTS_STREAM = "GAON_EVENTS";
+/** 잡 subject 접두. 큐별로 `gaon.jobs.<queue>` 하나. */
+export declare const JOBS_SUBJECT_PREFIX = "gaon.jobs";
+/** DLQ 는 단일 subject. */
+export declare const DLQ_SUBJECT = "gaon.dlq.jobs";
+/** 이벤트 subject 접두. 이벤트명별 `gaon.events.<name>`. */
+export declare const EVENTS_SUBJECT_PREFIX = "gaon.events";
+/** 큐 이름 → 잡 subject. 큐 이름은 임의 문자열이라 인코딩한다(keys.ts 근거). */
+export declare function jobSubject(queue: string): string;
+/** 큐 컨슈머의 durable 이름. */
+export declare function jobConsumerName(queue: string): string;
+/** 이벤트명 → subject. */
+export declare function eventSubject(name: string): string;
+/** 리스너 컨슈머의 durable 이름(리스너 키별로 유일). */
+export declare function listenerConsumerName(listenerId: string): string;
+/** ms → JetStream nanos(정수). */
+export declare function toNanos(ms: number): number;
+export interface StreamTuning {
+    /** 잡 중복 제거 창(ms). 크래시 재처리 시 재적재 중복을 흡수한다. 기본 120000. */
+    readonly dedupeWindowMs?: number;
+    /** DLQ 보존 기간(ms). 기본 14일. */
+    readonly dlqMaxAgeMs?: number;
+    /** 이벤트 보존 기간(ms). 기본 7일. */
+    readonly eventsMaxAgeMs?: number;
+}
+/**
+ * 잡 스트림을 보장한다(워크큐 보존). ack 된 메시지는 즉시 삭제되므로
+ * 큐가 밀리지 않는다. 재적재 중복 방어를 위해 중복 제거 창을 둔다.
+ */
+export declare function ensureJobsStream(nats: GaonNats, tuning?: StreamTuning): Promise<void>;
+/** DLQ 스트림을 보장한다(한도 보존 — 사람이 확인·재적재할 때까지 유지). */
+export declare function ensureDlqStream(nats: GaonNats, tuning?: StreamTuning): Promise<void>;
+/** 이벤트 스트림을 보장한다(한도 보존). 리스너별 durable 컨슈머가 소비한다. */
+export declare function ensureEventsStream(nats: GaonNats, tuning?: StreamTuning): Promise<void>;

package/dist/streams.js

@@ -0,0 +1,83 @@
+// @gaonjs/async · JetStream 스트림·컨슈머 토폴로지 (§7 M7)
+//
+// 비동기 배터리의 세 스트림을 여기서 선언·보장한다:
+//  - GAON_JOBS      잡 큐. 워크큐 보존(ack 되면 삭제) — 큐별 컨슈머가
+//                   겹치지 않는 subject 필터로 소비한다.
+//  - GAON_JOBS_DLQ  최대 재시도를 소진한 잡. 한도 보존(사람이 확인·재적재).
+//  - GAON_EVENTS    도메인 이벤트 pub/sub. 리스너별 durable 컨슈머가
+//                   각자 소비하므로 한도 보존(interest 아님 — 리스너가
+//                   나중에 붙어도 과거 이벤트를 받게).
+//
+// 스트림 add 는 멱등이다(같은 설정으로 다시 부르면 no-op). 워커·enqueue
+// 진입점에서 부팅 시 한 번 보장한다.
+import { jetstreamManager } from '@nats-io/jetstream';
+import { encodeSegment } from './keys.js';
+export const JOBS_STREAM = 'GAON_JOBS';
+export const DLQ_STREAM = 'GAON_JOBS_DLQ';
+export const EVENTS_STREAM = 'GAON_EVENTS';
+/** 잡 subject 접두. 큐별로 `gaon.jobs.<queue>` 하나. */
+export const JOBS_SUBJECT_PREFIX = 'gaon.jobs';
+/** DLQ 는 단일 subject. */
+export const DLQ_SUBJECT = 'gaon.dlq.jobs';
+/** 이벤트 subject 접두. 이벤트명별 `gaon.events.<name>`. */
+export const EVENTS_SUBJECT_PREFIX = 'gaon.events';
+/** 큐 이름 → 잡 subject. 큐 이름은 임의 문자열이라 인코딩한다(keys.ts 근거). */
+export function jobSubject(queue) {
+    return `${JOBS_SUBJECT_PREFIX}.${encodeSegment(queue)}`;
+}
+/** 큐 컨슈머의 durable 이름. */
+export function jobConsumerName(queue) {
+    return `gaon-jobs-${encodeSegment(queue)}`;
+}
+/** 이벤트명 → subject. */
+export function eventSubject(name) {
+    return `${EVENTS_SUBJECT_PREFIX}.${encodeSegment(name)}`;
+}
+/** 리스너 컨슈머의 durable 이름(리스너 키별로 유일). */
+export function listenerConsumerName(listenerId) {
+    return `gaon-listener-${encodeSegment(listenerId)}`;
+}
+/** ms → JetStream nanos(정수). */
+export function toNanos(ms) {
+    return Math.round(ms * 1e6);
+}
+const DEFAULT_DEDUPE_MS = 120000;
+const DEFAULT_DLQ_MAX_AGE_MS = 14 * 24 * 3600 * 1000;
+const DEFAULT_EVENTS_MAX_AGE_MS = 7 * 24 * 3600 * 1000;
+/**
+ * 잡 스트림을 보장한다(워크큐 보존). ack 된 메시지는 즉시 삭제되므로
+ * 큐가 밀리지 않는다. 재적재 중복 방어를 위해 중복 제거 창을 둔다.
+ */
+export async function ensureJobsStream(nats, tuning = {}) {
+    const jsm = await jetstreamManager(nats.nc);
+    await jsm.streams.add({
+        name: JOBS_STREAM,
+        subjects: [`${JOBS_SUBJECT_PREFIX}.>`],
+        retention: 'workqueue',
+        discard: 'old',
+        duplicate_window: toNanos(tuning.dedupeWindowMs ?? DEFAULT_DEDUPE_MS),
+    });
+}
+/** DLQ 스트림을 보장한다(한도 보존 — 사람이 확인·재적재할 때까지 유지). */
+export async function ensureDlqStream(nats, tuning = {}) {
+    const jsm = await jetstreamManager(nats.nc);
+    await jsm.streams.add({
+        name: DLQ_STREAM,
+        subjects: [DLQ_SUBJECT],
+        retention: 'limits',
+        max_age: toNanos(tuning.dlqMaxAgeMs ?? DEFAULT_DLQ_MAX_AGE_MS),
+    });
+}
+/** 이벤트 스트림을 보장한다(한도 보존). 리스너별 durable 컨슈머가 소비한다. */
+export async function ensureEventsStream(nats, tuning = {}) {
+    const jsm = await jetstreamManager(nats.nc);
+    await jsm.streams.add({
+        name: EVENTS_STREAM,
+        subjects: [`${EVENTS_SUBJECT_PREFIX}.>`],
+        retention: 'limits',
+        max_age: toNanos(tuning.eventsMaxAgeMs ?? DEFAULT_EVENTS_MAX_AGE_MS),
+        // 중복 제거 창: emit 멱등(같은 event id 재발행)과 아웃박스 릴레이의
+        // "발행 후 표시 사이 크래시" 재발행을 흡수한다(at-least-once → 사실상 1회).
+        duplicate_window: toNanos(tuning.dedupeWindowMs ?? DEFAULT_DEDUPE_MS),
+    });
+}

package/dist/work.d.ts

@@ -0,0 +1,52 @@
+import type { Kysely } from 'kysely';
+import type { GaonNats } from './nats.js';
+import { type WorkerHandle, type WorkerEvent } from './worker.js';
+import { type ListenerEvent } from './listeners.js';
+import { type SchedulerEvent, type ScheduleDef } from './schedule.js';
+import type { StreamTuning } from './streams.js';
+export type WorkEvent = {
+    readonly kind: 'worker';
+    readonly event: WorkerEvent;
+} | {
+    readonly kind: 'listener';
+    readonly event: ListenerEvent;
+} | {
+    readonly kind: 'scheduler';
+    readonly event: SchedulerEvent;
+} | {
+    readonly kind: 'relay';
+    readonly count: number;
+} | {
+    readonly kind: 'ready';
+    readonly jobs: number;
+    readonly listeners: number;
+    readonly scheduled: number;
+};
+export interface WorkOptions {
+    readonly nats: GaonNats;
+    /** 인스턴스 식별자(스케줄러 리스 값). */
+    readonly id: string;
+    /** 아웃박스 릴레이용 DB(생략 시 릴레이 미기동). */
+    readonly db?: Kysely<any>;
+    /** 스케줄 정의(생략 시 스케줄러 미기동). */
+    readonly schedule?: ScheduleDef;
+    /** 큐 기본 동시성. */
+    readonly concurrency?: number;
+    /** ack 대기(ms) — 초과 시 크래시로 보고 재전달(크래시 복구). 기본 30000. */
+    readonly ackWaitMs?: number;
+    /** graceful drain 상한(ms). 워커·리스너 공통. 기본 30000. */
+    readonly drainTimeoutMs?: number;
+    /** 릴레이 폴링 주기(ms). */
+    readonly relayPollMs?: number;
+    readonly tuning?: StreamTuning;
+    onEvent?(e: WorkEvent): void;
+}
+export interface WorkHandle {
+    stop(): Promise<void>;
+    readonly worker: WorkerHandle;
+}
+/**
+ * 워커 런타임을 조립·기동한다. 호출 전에 도메인 파일(잡·리스너·스케줄)을
+ * import 해 레지스트리를 채워 두어야 한다(파일=등록).
+ */
+export declare function runWork(opts: WorkOptions): Promise<WorkHandle>;

package/dist/work.js

@@ -0,0 +1,88 @@
+// @gaonjs/async · 워커 프로세스 런타임 (§7 M7 · line 863~885)
+//
+// `gaon work` 가 띄우는 운영 런타임. 도메인의 잡·리스너·스케줄·아웃박스를
+// 한 프로세스에 조립한다:
+//  - 잡 워커(runWorker)     — 큐 소비·재시도·DLQ
+//  - 리스너(runListeners)    — 이벤트 소비
+//  - 스케줄러(runScheduler)  — 리더 선출 단일 발행(선택)
+//  - 아웃박스 릴레이(runOutboxRelay) — DB→NATS 발행(DB 있을 때만)
+//
+// Graceful drain: stop() 이 전 구성요소를 순서대로 내린다 — 스케줄러(신규
+// 틱 중단·리더 반납) → 릴레이 → 리스너 → 워커(진행 잡 완료 대기). 워커·
+// 리스너가 진행 중 작업을 상한까지 기다리므로, 종료가 진행 잡을 자르지 않는다.
+import { configureJobs } from './jobs.js';
+import { configureEvents } from './events.js';
+import { runWorker } from './worker.js';
+import { runListeners } from './listeners.js';
+import { runScheduler } from './schedule.js';
+import { runOutboxRelay, ensureOutboxTable } from './outbox.js';
+import { registeredListeners } from './events.js';
+import { registeredJobs } from './jobs.js';
+/**
+ * 워커 런타임을 조립·기동한다. 호출 전에 도메인 파일(잡·리스너·스케줄)을
+ * import 해 레지스트리를 채워 두어야 한다(파일=등록).
+ */
+export async function runWork(opts) {
+    const emit = (e) => opts.onEvent?.(e);
+    // enqueue·emit 전송 배선(재시도 재적재·잡→잡·즉시 발행 경로).
+    configureJobs(opts.nats, opts.tuning);
+    configureEvents(opts.nats, opts.tuning);
+    const worker = await runWorker({
+        nats: opts.nats,
+        concurrency: opts.concurrency,
+        ackWaitMs: opts.ackWaitMs,
+        drainTimeoutMs: opts.drainTimeoutMs,
+        tuning: opts.tuning,
+        onEvent: (event) => emit({ kind: 'worker', event }),
+    });
+    const listeners = registeredListeners().length
+        ? await runListeners({
+            nats: opts.nats,
+            ackWaitMs: opts.ackWaitMs,
+            drainTimeoutMs: opts.drainTimeoutMs,
+            tuning: opts.tuning,
+            onEvent: (event) => emit({ kind: 'listener', event }),
+        })
+        : undefined;
+    let relay;
+    if (opts.db) {
+        await ensureOutboxTable(opts.db);
+        relay = runOutboxRelay(opts.db, {
+            pollMs: opts.relayPollMs,
+            onRelayed: (count) => emit({ kind: 'relay', count }),
+        });
+    }
+    let scheduler;
+    if (opts.schedule && opts.schedule.entries.length > 0) {
+        scheduler = await runScheduler({
+            nats: opts.nats,
+            def: opts.schedule,
+            id: opts.id,
+            onEvent: (event) => emit({ kind: 'scheduler', event }),
+        });
+    }
+    emit({
+        kind: 'ready',
+        jobs: registeredJobs().length,
+        listeners: registeredListeners().length,
+        scheduled: opts.schedule?.entries.length ?? 0,
+    });
+    let stopped = false;
+    return {
+        worker,
+        async stop() {
+            if (stopped)
+                return;
+            stopped = true;
+            // 스케줄러 먼저 — 신규 틱 중단·리더 반납(다른 인스턴스가 즉시 승계).
+            if (scheduler)
+                await scheduler.stop();
+            if (relay)
+                await relay.stop();
+            // 리스너·워커는 진행 중 작업을 상한까지 기다린 뒤 내려간다.
+            if (listeners)
+                await listeners.stop();
+            await worker.stop();
+        },
+    };
+}

package/dist/worker.d.ts

@@ -0,0 +1,71 @@
+import type { GaonNats } from './nats.js';
+import { type StreamTuning } from './streams.js';
+/** DLQ 레코드(사람이 확인·재적재). */
+export interface DlqRecord {
+    readonly id: string;
+    readonly name: string;
+    readonly queue: string;
+    readonly args: readonly unknown[];
+    readonly attempts: number;
+    readonly error: string;
+    readonly failedAt: number;
+    readonly enqueuedAt: number;
+}
+export type WorkerEvent = {
+    readonly kind: 'processing';
+    readonly job: string;
+    readonly id: string;
+    readonly attempt: number;
+} | {
+    readonly kind: 'succeeded';
+    readonly job: string;
+    readonly id: string;
+} | {
+    readonly kind: 'retrying';
+    readonly job: string;
+    readonly id: string;
+    readonly attempt: number;
+    readonly delayMs: number;
+} | {
+    readonly kind: 'deferred';
+    readonly job: string;
+    readonly id: string;
+    readonly delayMs: number;
+} | {
+    readonly kind: 'dead';
+    readonly job: string;
+    readonly id: string;
+    readonly attempts: number;
+    readonly error: string;
+} | {
+    readonly kind: 'skipped';
+    readonly name: string;
+    readonly id: string;
+} | {
+    readonly kind: 'error';
+    readonly error: string;
+};
+export interface WorkerOptions {
+    readonly nats: GaonNats;
+    /** 큐별 기본 동시성. 잡 옵션의 concurrency 가 우선. 기본 1. */
+    readonly concurrency?: number;
+    /** ack 대기(ms) — 이 시간 안에 ack/nak 없으면 크래시로 보고 재전달. 기본 30000. */
+    readonly ackWaitMs?: number;
+    /** graceful drain 상한(ms). 기본 30000. */
+    readonly drainTimeoutMs?: number;
+    /** 스트림 튜닝(중복 창 등). */
+    readonly tuning?: StreamTuning;
+    /** 진행 이벤트 통지(로깅·테스트). */
+    onEvent?(e: WorkerEvent): void;
+}
+export interface WorkerHandle {
+    /** graceful drain: 신규 pull 중단 → 진행 잡 완료 대기 → 종료. */
+    stop(): Promise<void>;
+    /** 현재 처리 중(in-flight) 잡 수. */
+    readonly inflight: number;
+}
+/**
+ * 워커를 시작한다. registeredQueues() 의 각 큐에 컨슈머를 붙인다 —
+ * 호출 전에 잡 파일을 import 해 레지스트리를 채워 두어야 한다.
+ */
+export declare function runWorker(opts: WorkerOptions): Promise<WorkerHandle>;

package/dist/worker.js

@@ -0,0 +1,179 @@
+// @gaonjs/async · 잡 워커 (§7 M7 · line 858~886)
+//
+// `gaon work` 프로세스의 심장. 등록된 잡의 큐마다 JetStream pull 컨슈머를
+// 만들어 메시지를 당겨 처리한다. 처리 규칙:
+//  - notBefore 미도래(지연·백오프 대기) → nak(남은 시간)로 정확히 그 시각에
+//    재전달되게 미룬다(§7 line 792 "NAK 지연 기반").
+//  - 성공 → ack(워크큐 보존이라 삭제된다).
+//  - 실패 & 재시도 여분 있음 → attempt+1·notBefore=now+백오프 로 재적재 후 ack.
+//  - 실패 & 재시도 소진 → DLQ 로 옮기고 term(더 재전달 안 함).
+//  - 파싱 불가(포이즌) → 즉시 term.
+//
+// JetStream 의 네이티브 재전달(ack_wait·max_deliver)은 정상 재시도가 아니라
+// **크래시 복구**용이다: 워커가 잡을 붙든 채 죽으면 ack_wait 만료로 스트림에
+// 되돌아가 다른 워커가 다시 처리한다(at-least-once — 잡은 멱등 권장).
+//
+// Graceful drain(§7 line 885): 종료 시그널 → 신규 pull 중단 → 진행 잡 완료
+// 대기(timeout) → 종료. 미완료 잡은 ack 타임아웃으로 스트림에 남는다.
+import { runWithLogContext } from '@gaonjs/core';
+import { jetstreamManager } from '@nats-io/jetstream';
+import { JOBS_STREAM, DLQ_SUBJECT, jobConsumerName, jobSubject, toNanos, ensureJobsStream, ensureDlqStream, } from './streams.js';
+import { encodePayloadBytes, decodePayloadBytes } from './codec.js';
+import { backoffDelayMs } from './backoff.js';
+import { configureJobs, getJob, registeredQueues, registeredJobs, enqueueRaw, DEFAULT_QUEUE, } from './jobs.js';
+const DEFAULT_ACK_WAIT_MS = 30000;
+const DEFAULT_DRAIN_MS = 30000;
+/**
+ * 워커를 시작한다. registeredQueues() 의 각 큐에 컨슈머를 붙인다 —
+ * 호출 전에 잡 파일을 import 해 레지스트리를 채워 두어야 한다.
+ */
+export async function runWorker(opts) {
+    const ackWaitMs = opts.ackWaitMs ?? DEFAULT_ACK_WAIT_MS;
+    const drainTimeoutMs = opts.drainTimeoutMs ?? DEFAULT_DRAIN_MS;
+    const emit = (e) => opts.onEvent?.(e);
+    // enqueue 전송도 워커에서 필요하다(재시도 재적재·잡→잡 큐잉).
+    configureJobs(opts.nats, opts.tuning);
+    await ensureJobsStream(opts.nats, opts.tuning);
+    await ensureDlqStream(opts.nats, opts.tuning);
+    const jsm = await jetstreamManager(opts.nats.nc);
+    const toDlq = async (rec) => {
+        await opts.nats.js.publish(DLQ_SUBJECT, encodePayloadBytes(rec), { msgID: `${rec.id}#dead` });
+    };
+    // 한 메시지 처리: notBefore·성공·재시도·DLQ 규칙을 적용한다.
+    const handleMessage = async (m) => {
+        let msg;
+        try {
+            msg = decodePayloadBytes(m.data);
+        }
+        catch {
+            // 포이즌(파싱 불가) — 무한 재전달을 막으려 즉시 폐기한다.
+            emit({ kind: 'skipped', name: '(unparseable)', id: '?' });
+            m.term();
+            return;
+        }
+        const now = Date.now();
+        if (now < msg.notBefore) {
+            // 아직 실행 시각 전 — 남은 시간만큼 정확히 미룬다(지연·백오프).
+            const delayMs = msg.notBefore - now;
+            emit({ kind: 'deferred', job: msg.name, id: msg.id, delayMs });
+            m.nak(delayMs);
+            return;
+        }
+        const def = getJob(msg.name);
+        if (!def) {
+            // 이 워커에 해당 잡이 등록돼 있지 않다 — 다른 워커 몫일 수 있으니
+            // 잠시 뒤 재전달되게 미룬다(포이즌 취급하지 않는다).
+            emit({ kind: 'skipped', name: msg.name, id: msg.id });
+            m.nak(1000);
+            return;
+        }
+        const attempt = msg.attempt + 1;
+        const maxAttempts = 1 + (def.options.retries ?? 3);
+        emit({ kind: 'processing', job: msg.name, id: msg.id, attempt });
+        // 긴 잡이 ack_wait 를 넘겨 조기 재전달되지 않게 주기적으로 working() 을
+        // 보내 리스를 연장한다.
+        const heartbeat = setInterval(() => {
+            try {
+                m.working();
+            }
+            catch {
+                // 이미 ack/term 된 뒤면 무시.
+            }
+        }, Math.max(1000, Math.floor(ackWaitMs / 2)));
+        try {
+            const run = def.handler;
+            // 잡 실행을 로그 컨텍스트로 감싼다(§7) — 잡 본문의 모든 log.* 에 잡
+            // 이름·상관 ID·attempt 가 자동으로 붙어 HTTP 요청과 같은 추적성을 준다.
+            await runWithLogContext({ requestId: msg.id, jobName: msg.name, attempt }, () => run(...msg.args));
+            clearInterval(heartbeat);
+            m.ack();
+            emit({ kind: 'succeeded', job: msg.name, id: msg.id });
+        }
+        catch (err) {
+            clearInterval(heartbeat);
+            const error = err instanceof Error ? err.message : String(err);
+            if (attempt < maxAttempts) {
+                const delayMs = backoffDelayMs(attempt, def.options);
+                // attempt·notBefore 를 올려 재적재하고 현재 메시지는 ack 로 치운다.
+                await enqueueRaw({ ...msg, attempt, notBefore: Date.now() + delayMs });
+                m.ack();
+                emit({ kind: 'retrying', job: msg.name, id: msg.id, attempt, delayMs });
+            }
+            else {
+                await toDlq({
+                    id: msg.id,
+                    name: msg.name,
+                    queue: msg.queue,
+                    args: msg.args,
+                    attempts: attempt,
+                    error,
+                    failedAt: Date.now(),
+                    enqueuedAt: msg.enqueuedAt,
+                });
+                m.term();
+                emit({ kind: 'dead', job: msg.name, id: msg.id, attempts: attempt, error });
+            }
+        }
+    };
+    // 큐마다 컨슈머를 붙이고 동시성 제한 소비 루프를 돈다.
+    const queues = registeredQueues();
+    if (queues.length === 0)
+        queues.push(DEFAULT_QUEUE);
+    const closers = [];
+    const inflightAll = new Set();
+    for (const queue of queues) {
+        const durable = jobConsumerName(queue);
+        // 큐 동시성: 이 큐에 속한 잡 중 최댓값(없으면 워커 기본).
+        const declared = registeredJobs()
+            .filter((d) => d.queue === queue)
+            .map((d) => d.options.concurrency ?? 0);
+        const perQueueConc = Math.max(0, ...declared) || (opts.concurrency ?? 1);
+        await jsm.consumers.add(JOBS_STREAM, {
+            durable_name: durable,
+            filter_subject: jobSubject(queue),
+            ack_policy: 'explicit',
+            ack_wait: toNanos(ackWaitMs),
+            // 정상 재시도는 우리가 재적재로 처리한다. 네이티브 재전달은 크래시
+            // 복구용이라 상한만 둔다(포이즌 크래시 루프 방지).
+            max_deliver: 25,
+            max_ack_pending: 1000,
+        });
+        const consumer = await opts.nats.js.consumers.get(JOBS_STREAM, durable);
+        const messages = await consumer.consume({ max_messages: perQueueConc });
+        const loop = (async () => {
+            for await (const m of messages) {
+                const p = handleMessage(m).finally(() => inflightAll.delete(p));
+                inflightAll.add(p);
+                if (inflightAll.size >= perQueueConc)
+                    await Promise.race(inflightAll);
+            }
+        })();
+        closers.push(async () => {
+            // 신규 pull 중단(진행 중인 in-flight 는 아래에서 대기).
+            messages.stop();
+            await loop.catch(() => { });
+        });
+    }
+    let stopped = false;
+    return {
+        get inflight() {
+            return inflightAll.size;
+        },
+        async stop() {
+            if (stopped)
+                return;
+            stopped = true;
+            // 1) 신규 pull 중단.
+            for (const close of closers)
+                await close();
+            // 2) 진행 잡 완료 대기(상한). 남으면 ack_wait 로 스트림에 되돌아간다.
+            const deadline = Date.now() + drainTimeoutMs;
+            while (inflightAll.size > 0 && Date.now() < deadline) {
+                await Promise.race([...inflightAll, delay(200)]);
+            }
+        },
+    };
+}
+function delay(ms) {
+    return new Promise((r) => setTimeout(r, ms));
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gaonjs/async",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "Gaon NATS 통합: 잡·이벤트·스케줄러·채널(ws)·허브(프레즌스) (구현 예정)",
   "type": "module",
   "license": "MIT",
@@ -27,7 +27,8 @@
     "@nats-io/transport-node": "^3.1.0",
     "@nats-io/jetstream": "^3.1.0",
     "@nats-io/kv": "^3.1.0",
-    "@gaonjs/core": "0.1.3"
+    "kysely": "^0.29.4",
+    "@gaonjs/core": "0.1.4"
   },
   "scripts": {
     "build": "node ../../node_modules/typescript/bin/tsc -p tsconfig.json"