@gaonjs/async 0.2.0 → 0.2.2

package/dist/hub.js

@@ -1,126 +1,227 @@
-// @gaonjs/async · 허브 서버 (§7 실시간 · 질문 19)
+// @gaonjs/async · 허브 서버 (§7 실시간 · errata E-2 2026-07-23)
 //
-// 허브는 접속자 목록의 **단일 권위이자 중계**다. 웹서버들이 보내는
-// 프레즌스 명령(join/leave/heartbeat)을 받아 **NATS KV 에 영속**하고(허브만
-// KV 를 쓴다), 변경 델타를 전 웹서버로 브로드캐스트한다. HA 는 스케줄러와
-// 동일한 **리스 기반 리더 선출**(active-standby) — 리더만 명령을 처리한다.
+// 허브는 접속자 목록의 **단일 권위이자 중계**다. 웹서버들은 허브에 **TCP
+// 지속 연결**로 붙어(라인 구분 JSON) 프레즌스 명령(register/join/leave/
+// unregister/ping)을 보낸다. 허브는 이를 **NATS KV 에 영속**(허브만 KV 를
+// 쓴다)하고, 변경 델타를 **NATS pub/sub**(broadcast 전용)으로 전 웹서버에
+// 중계한다. HA 는 리스 기반 리더 선출(active-standby) — **리더만 TCP 를
+// bind** 한다.
 //
-// - 재시작 복원: 리더가 되면 KV 의 기존 로스터로 생존 추적을 재구축한다.
-//   접속자 목록 자체는 KV 에 남아 있으므로 허브가 죽어도 유실되지 않는다
-//   (웹서버의 list() 는 KV 를 직접 읽는다).
-// - 생존 추적: 웹서버가 죽어 하트비트가 끊긴 멤버는 임계 시간 후 만료시켜
-//   leave 로 처리한다(§7 line 898).
+// 즉시 죽음 감지(errata E-2 핵심): 웹서버 프로세스가 죽거나 파티션되면 그
+// TCP 소켓이 끊기고, 허브는 `socket.on('close')` 에서 **그 서버의 모든
+// 멤버를 즉시 정리**(KV delete + leave 델타)한다 — 하트비트 타임아웃을
+// 기다리지 않는다. 반쯤 열린 TCP(파티션에서 FIN 유실)는 앱 레벨 ping
+// 타임아웃(서버당 1건)으로 백스톱한다.
+//
+// - 재시작 복원: 리더가 되면 KV 로스터로 서버별 멤버 맵을 재구축한다. 접속자
+//   목록은 KV 에 남아 허브가 죽어도 유실되지 않는다(웹서버 list() 는 KV 직접
+//   읽기). 재접속 안 되는 서버(허브+서버 동시 장애)는 grace 후 회수한다.
+import { createServer } from 'node:net';
 import { leaseLeader } from './lease.js';
 import { PRESENCE_BUCKET } from './presence.js';
 import { presenceKey, parsePresenceKey } from './keys.js';
-import { HUB_PRESENCE_SUBJECT, presenceEventSubject, encodeJson, decodeJson, } from './protocol.js';
-/** now 주입 없이 테스트 결정성을 위해 Date.now 를 감싼다. */
+import { presenceEventSubject, encodeJson, decodeJson, createLineDecoder, HUB_ENDPOINT_BUCKET, HUB_ENDPOINT_KEY, } from './protocol.js';
 const now = () => Date.now();
-/**
- * 허브를 시작한다. 리더가 되기 전에는 대기하고, 리더가 되면 프레즌스
- * 명령 구독·KV 권위 갱신·델타 중계·만료 스윕을 켠다.
- */
+const DEFAULT_PORT = 4001;
 export async function runHub(opts) {
-    const memberTimeoutMs = opts.memberTimeoutMs ?? 30000;
-    const sweepMs = opts.sweepMs ?? 5000;
+    const port = opts.port ?? DEFAULT_PORT;
+    const host = opts.host ?? '0.0.0.0';
+    const advertiseAddr = opts.advertiseAddr ?? `127.0.0.1:${port}`;
+    const pingTimeoutMs = opts.pingTimeoutMs ?? 10000;
+    const sweepMs = opts.sweepMs ?? 2000;
+    const reclaimGraceMs = opts.reclaimGraceMs ?? 15000;
     const kv = await opts.nats.kv(PRESENCE_BUCKET);
-    // 리더일 때만 살아 있는 자원.
-    let sub;
+    // ── 리더일 때만 살아 있는 상태 ──
+    let tcp;
+    let boundPort;
     let sweepTimer;
-    // 멤버별 마지막 생존 시각(KV 키 → ts). 리더 승격 시 KV 에서 복원.
-    const lastSeen = new Map();
+    // 소켓 → serverId, serverId → (presenceKey → {channel,member}), 소켓 무활동 추적.
+    const socketServer = new Map();
+    const serverMembers = new Map();
+    const socketSeen = new Map();
+    // 복원됐지만 아직 재접속(register) 안 된 서버 → 복원 시각(회수 유예 판단).
+    const unclaimedSince = new Map();
+    // 재접속 reconcile: register~synced 사이, 아직 재join 안 된 옛 멤버 키(소켓별).
+    const reconciling = new Map();
+    const emitError = (err) => opts.onError?.(err instanceof Error ? err : new Error(String(err)));
     const broadcast = (channel, ev) => {
         opts.nats.nc.publish(presenceEventSubject(channel), encodeJson(ev));
     };
-    const applyJoin = async (channel, member, info, server) => {
-        const key = presenceKey(channel, member);
-        const rec = { info, server, ts: now() };
-        await kv.put(key, encodeJson(rec));
-        lastSeen.set(key, rec.ts);
-        broadcast(channel, { type: 'join', channel, member: { id: member, info } });
-    };
-    const applyLeave = async (channel, member) => {
-        const key = presenceKey(channel, member);
-        await kv.delete(key).catch(() => { });
-        lastSeen.delete(key);
+    const delMember = async (channel, member) => {
+        await kv.delete(presenceKey(channel, member)).catch(() => { });
         broadcast(channel, { type: 'leave', channel, member });
     };
-    const applyHeartbeat = async (channel, member) => {
-        const key = presenceKey(channel, member);
-        const entry = await kv.get(key);
-        if (!entry)
-            return; // join 을 놓친 하트비트는 무시(다음 join 에서 정합).
-        const rec = decodeJson(entry.value);
-        if (!rec)
+    /** 한 서버의 모든 멤버를 즉시 정리(KV delete + leave 델타). */
+    const cleanupServer = async (server) => {
+        const members = serverMembers.get(server);
+        serverMembers.delete(server);
+        unclaimedSince.delete(server);
+        if (!members)
             return;
-        const bumped = { ...rec, ts: now() };
-        await kv.put(key, encodeJson(bumped));
-        lastSeen.set(key, bumped.ts);
-    };
-    const handleCommand = async (cmd) => {
-        if (cmd.op === 'join')
-            await applyJoin(cmd.channel, cmd.member, cmd.info, cmd.server);
-        else if (cmd.op === 'leave')
-            await applyLeave(cmd.channel, cmd.member);
-        else
-            await applyHeartbeat(cmd.channel, cmd.member);
+        for (const { channel, member } of members.values())
+            await delMember(channel, member);
     };
-    const sweep = async () => {
-        const cutoff = now() - memberTimeoutMs;
-        for (const [key, ts] of [...lastSeen.entries()]) {
-            if (ts < cutoff) {
-                const { channel, member } = parsePresenceKey(key);
-                await applyLeave(channel, member);
+    const handleCommand = async (socket, cmd) => {
+        socketSeen.set(socket, now());
+        switch (cmd.op) {
+            case 'register': {
+                // 재접속·failover 복원 대비: 옛 멤버를 지우지 않고 보존한다(flicker 방지).
+                // 곧 오는 resync(join)로 재확인하고, 재join 안 된 멤버는 synced 에서 정리.
+                socketServer.set(socket, cmd.server);
+                const existing = serverMembers.get(cmd.server);
+                if (existing)
+                    reconciling.set(socket, new Set(existing.keys()));
+                else
+                    serverMembers.set(cmd.server, new Map());
+                unclaimedSince.delete(cmd.server);
+                break;
             }
+            case 'join': {
+                const server = socketServer.get(socket);
+                if (!server)
+                    break;
+                const key = presenceKey(cmd.channel, cmd.member);
+                const map = serverMembers.get(server);
+                const isNew = !map?.has(key);
+                map?.set(key, { channel: cmd.channel, member: cmd.member });
+                reconciling.get(socket)?.delete(key); // 재확인된 멤버 — 정리 대상에서 제외
+                await kv.put(presenceKey(cmd.channel, cmd.member), encodeJson({ info: cmd.info, server, ts: now() }));
+                // 새 멤버만 델타 방송(재접속 시 기존 멤버는 중복 방송 안 함).
+                if (isNew)
+                    broadcast(cmd.channel, { type: 'join', channel: cmd.channel, member: { id: cmd.member, info: cmd.info } });
+                break;
+            }
+            case 'leave': {
+                const server = socketServer.get(socket);
+                if (!server)
+                    break;
+                serverMembers.get(server)?.delete(presenceKey(cmd.channel, cmd.member));
+                await delMember(cmd.channel, cmd.member);
+                break;
+            }
+            case 'synced': {
+                // resync 완료 — 재확인 안 된 옛 멤버(재접속 중 떠남)를 정리.
+                const server = socketServer.get(socket);
+                const pending = reconciling.get(socket);
+                reconciling.delete(socket);
+                if (server && pending) {
+                    const map = serverMembers.get(server);
+                    for (const key of pending) {
+                        const m = map?.get(key);
+                        map?.delete(key);
+                        if (m)
+                            await delMember(m.channel, m.member);
+                    }
+                }
+                break;
+            }
+            case 'unregister': {
+                // graceful 종료 — 그 서버 전원 즉시 정리.
+                await cleanupServer(cmd.server);
+                break;
+            }
+            case 'ping':
+                break; // socketSeen 갱신만(위)
         }
     };
-    // 리더 승격: KV 로스터로 생존 추적 재구축(재시작 복원).
+    const onSocket = (socket) => {
+        socket.setNoDelay(true);
+        socketSeen.set(socket, now());
+        const decode = createLineDecoder();
+        socket.setEncoding('utf8');
+        socket.on('data', (chunk) => {
+            for (const cmd of decode(chunk))
+                void handleCommand(socket, cmd).catch(emitError);
+        });
+        const onGone = () => {
+            const server = socketServer.get(socket);
+            socketServer.delete(socket);
+            socketSeen.delete(socket);
+            reconciling.delete(socket);
+            // ★ 즉시 죽음 감지: 소켓이 끊기면 그 서버 전 멤버를 곧바로 정리한다.
+            if (server)
+                void cleanupServer(server).catch(emitError);
+        };
+        socket.on('close', onGone);
+        socket.on('error', () => {
+            /* close 가 뒤따르며 onGone 이 정리한다 */
+        });
+    };
+    /** 반쯤 열린 소켓(파티션) 백스톱 + 미회수 복원 서버 회수. */
+    const sweep = () => {
+        const t = now();
+        for (const [socket, seen] of [...socketSeen.entries()]) {
+            if (t - seen > pingTimeoutMs)
+                socket.destroy(); // → close → cleanupServer
+        }
+        for (const [server, since] of [...unclaimedSince.entries()]) {
+            if (t - since > reclaimGraceMs)
+                void cleanupServer(server).catch(emitError);
+        }
+    };
+    /** 리더 승격: KV 로스터로 서버별 멤버 맵을 재구축(재시작 복원). */
     const restoreFromKv = async () => {
-        lastSeen.clear();
-        const iter = await kv.keys();
-        for await (const key of iter) {
+        serverMembers.clear();
+        unclaimedSince.clear();
+        for await (const key of await kv.keys()) {
             const entry = await kv.get(key);
             if (!entry)
                 continue;
             const rec = decodeJson(entry.value);
-            if (rec)
-                lastSeen.set(key, rec.ts);
+            if (!rec)
+                continue;
+            const { channel, member } = parsePresenceKey(key);
+            if (!serverMembers.has(rec.server)) {
+                serverMembers.set(rec.server, new Map());
+                unclaimedSince.set(rec.server, now()); // 재접속 없으면 grace 후 회수
+            }
+            serverMembers.get(rec.server).set(key, { channel, member });
         }
     };
+    const announceEndpoint = async () => {
+        const ekv = await opts.nats.kv(HUB_ENDPOINT_BUCKET);
+        await ekv.put(HUB_ENDPOINT_KEY, encodeJson({ addr: advertiseAddr })).catch(() => { });
+    };
+    const clearEndpoint = async () => {
+        const ekv = await opts.nats.kv(HUB_ENDPOINT_BUCKET);
+        await ekv.delete(HUB_ENDPOINT_KEY).catch(() => { });
+    };
     const startLeading = async () => {
-        // 구독을 먼저 켜서 승격 직후 도착하는 명령을 놓치지 않는다(복원은 그 뒤).
-        // 리더만 구독한다 — 대기 인스턴스는 명령을 처리하지 않는다. 큐 그룹으로
-        // 리더 교대 순간의 중복 처리를 막는다.
-        const subscription = opts.nats.nc.subscribe(HUB_PRESENCE_SUBJECT, { queue: 'gaon-hub' });
-        sub = subscription;
-        (async () => {
-            for await (const m of subscription) {
-                const cmd = decodeJson(m.data);
-                if (!cmd)
-                    continue;
-                try {
-                    await handleCommand(cmd);
-                }
-                finally {
-                    // join/leave 는 request/reply — 반영 후 ack. heartbeat 는 reply 없음.
-                    if (m.reply)
-                        m.respond(encodeJson({ ok: true }));
-                }
-            }
-        })();
-        sweepTimer = setInterval(() => void sweep(), sweepMs);
-        // KV 로스터로 생존 추적 재구축(재시작 복원). 명령 처리와 병행돼도
-        // 안전하다(둘 다 lastSeen 을 덮어쓸 뿐).
         await restoreFromKv();
+        await new Promise((resolve, reject) => {
+            const server = createServer(onSocket);
+            server.on('error', (err) => {
+                emitError(err);
+                reject(err);
+            });
+            server.listen(port, host, () => {
+                const addr = server.address();
+                boundPort = typeof addr === 'object' && addr ? addr.port : port;
+                tcp = server;
+                resolve();
+            });
+        });
+        sweepTimer = setInterval(sweep, sweepMs);
+        await announceEndpoint();
         opts.onState?.({ leader: true });
     };
-    const stopLeading = () => {
-        sub?.unsubscribe();
-        sub = undefined;
+    const stopLeading = async () => {
         if (sweepTimer)
             clearInterval(sweepTimer);
         sweepTimer = undefined;
-        lastSeen.clear();
+        for (const socket of [...socketServer.keys()])
+            socket.destroy();
+        socketServer.clear();
+        socketSeen.clear();
+        serverMembers.clear();
+        unclaimedSince.clear();
+        await clearEndpoint();
+        if (tcp) {
+            const server = tcp;
+            tcp = undefined;
+            boundPort = undefined;
+            await new Promise((resolve) => server.close(() => resolve()));
+        }
         opts.onState?.({ leader: false });
     };
     const lease = await leaseLeader({
@@ -128,15 +229,18 @@ export async function runHub(opts) {
         key: 'hub.leader',
         id: opts.id,
         ttlMs: opts.ttlMs,
-        onElected: () => void startLeading(),
-        onRevoked: () => stopLeading(),
+        onElected: () => void startLeading().catch(emitError),
+        onRevoked: () => void stopLeading().catch(emitError),
     });
     return {
         get isLeader() {
             return lease.isLeader;
         },
+        get port() {
+            return boundPort;
+        },
         async stop() {
-            stopLeading();
+            await stopLeading();
             await lease.stop();
         },
     };

package/dist/index.d.ts

@@ -7,3 +7,17 @@ export { createPresenceClient, PRESENCE_BUCKET, type PresenceClient, type Presen
 export { createChannelRuntime, type ChannelRuntime, type ChannelRuntimeOptions, type SocketAdapter, type JoinRequest, type Connection, } from './runtime.js';
 export { runHub, type HubOptions, type HubHandle } from './hub.js';
 export { HUB_PRESENCE_SUBJECT, presenceEventSubject, encodeJson, decodeJson, type ClientMessage, type ServerFrame, type PresenceCommand, type PresenceEvent, type BroadcastEnvelope, } from './protocol.js';
+export { job, configureJobs, resetJobs, registerJob, getJob, registeredJobs, registeredQueues, isJobDef, enqueueRaw, DEFAULT_QUEUE, JOB_BRAND, type JobDef, type JobOptions, type JobMessage, } from './jobs.js';
+export { backoffDelayMs, DEFAULT_BACKOFF_MS, DEFAULT_RETRIES, type BackoffOptions, } from './backoff.js';
+export { parseDuration } from './duration.js';
+export { encodePayload, decodePayload, encodePayloadBytes, decodePayloadBytes, } from './codec.js';
+export { ensureJobsStream, ensureDlqStream, ensureEventsStream, jobSubject, eventSubject, JOBS_STREAM, DLQ_STREAM, EVENTS_STREAM, DLQ_SUBJECT, type StreamTuning, } from './streams.js';
+export { runWorker, type WorkerOptions, type WorkerHandle, type WorkerEvent, type DlqRecord, } from './worker.js';
+export { listDlq, findDlq, retryDlq, purgeDlq, type DlqEntry, } from './dlq.js';
+export { event, on, configureEvents, resetEvents, registeredListeners, isListener, reidentifyListener, publishToSubject, LISTENER_BRAND, type EventDef, type Listener, type PayloadOf, } from './events.js';
+export { runWork, type WorkOptions, type WorkHandle, type WorkEvent } from './work.js';
+export { runListeners, type ListenersOptions, type ListenersHandle, type ListenerEvent, } from './listeners.js';
+export { runInTransaction, runOutboxRelay, ensureOutboxTable, OUTBOX_TABLE, type RelayOptions, type RelayHandle, } from './outbox.js';
+export { currentOutbox, runWithOutbox, type OutboxStager } from './outboxContext.js';
+export { schedule, runScheduler, type ScheduleDef, type ScheduleEntry, type ScheduleBuilder, type Schedulable, type SchedulerOptions, type SchedulerHandle, type SchedulerEvent, } from './schedule.js';
+export { parseCron, type CronMatcher } from './cron.js';

package/dist/index.js

@@ -22,3 +22,30 @@ export { createChannelRuntime, } from './runtime.js';
 export { runHub } from './hub.js';
 // 와이어 프로토콜 (프레임·subject·직렬화)
 export { HUB_PRESENCE_SUBJECT, presenceEventSubject, encodeJson, decodeJson, } from './protocol.js';
+// ── 비동기 배터리 (M7) ───────────────────────────────────────────────────
+// 잡 레이어 (§7 · job()·enqueue·큐)
+export { job, configureJobs, resetJobs, registerJob, getJob, registeredJobs, registeredQueues, isJobDef, enqueueRaw, DEFAULT_QUEUE, JOB_BRAND, } from './jobs.js';
+// 백오프 곡선 (§7 · 재시도)
+export { backoffDelayMs, DEFAULT_BACKOFF_MS, DEFAULT_RETRIES, } from './backoff.js';
+// 기간 문자열 파서 (지연·스케줄)
+export { parseDuration } from './duration.js';
+// 잡·이벤트 페이로드 코덱 (bigint·Date 왕복)
+export { encodePayload, decodePayload, encodePayloadBytes, decodePayloadBytes, } from './codec.js';
+// JetStream 스트림 토폴로지
+export { ensureJobsStream, ensureDlqStream, ensureEventsStream, jobSubject, eventSubject, JOBS_STREAM, DLQ_STREAM, EVENTS_STREAM, DLQ_SUBJECT, } from './streams.js';
+// 잡 워커 (§7 · pull 컨슈머·재시도·DLQ·graceful drain)
+export { runWorker, } from './worker.js';
+// DLQ 조회·재적재 (§7 · gaon jobs list/retry)
+export { listDlq, findDlq, retryDlq, purgeDlq, } from './dlq.js';
+// 이벤트 버스 (§7 · event()·on()·emit)
+export { event, on, configureEvents, resetEvents, registeredListeners, isListener, reidentifyListener, publishToSubject, LISTENER_BRAND, } from './events.js';
+// 워커 프로세스 런타임 (§7 · gaon work 조립 · graceful drain)
+export { runWork } from './work.js';
+// 리스너 소비 (§7 · durable 컨슈머·재시도)
+export { runListeners, } from './listeners.js';
+// 아웃박스 패턴 (§7 · 트랜잭션 정합·릴레이 · v1 코어 내장)
+export { runInTransaction, runOutboxRelay, ensureOutboxTable, OUTBOX_TABLE, } from './outbox.js';
+export { currentOutbox, runWithOutbox } from './outboxContext.js';
+// 스케줄러 (§7 · schedule DSL·크론·리더 선출 단일 발행)
+export { schedule, runScheduler, } from './schedule.js';
+export { parseCron } from './cron.js';

package/dist/jobs.d.ts

@@ -0,0 +1,75 @@
+import type { GaonNats } from './nats.js';
+import type { BackoffOptions } from './backoff.js';
+import { type StreamTuning } from './streams.js';
+/** 큐 기본 이름. `{ queue }` 미지정 시. */
+export declare const DEFAULT_QUEUE = "default";
+/** 잡 옵션. 재시도·백오프·큐·동시성(§7 line 883). */
+export interface JobOptions extends BackoffOptions {
+    /** 잡 이름. 생략 시 파일 로더가 파일명에서 채운다(파일=등록 관례). */
+    readonly name?: string;
+    /** 처리 큐. 생략 시 'default'. 큐별로 컨슈머·동시성이 분리된다. */
+    readonly queue?: string;
+    /** 최대 재시도(최초 실행 제외). 총 시도 = 1 + retries. 기본 3. */
+    readonly retries?: number;
+    /** 이 큐 워커의 동시 처리 수. 기본 1. worker 가 소비한다. */
+    readonly concurrency?: number;
+}
+/** 큐로 오가는 잡 메시지(와이어). */
+export interface JobMessage {
+    readonly id: string;
+    readonly name: string;
+    readonly queue: string;
+    readonly args: readonly unknown[];
+    /** 방금까지 소진한 시도 번호(0=최초 실행 전). 재시도마다 +1. */
+    readonly attempt: number;
+    /** 실행 하한 시각(epoch ms). 지연·백오프를 표현한다. */
+    readonly notBefore: number;
+    readonly enqueuedAt: number;
+}
+/** 파일 로더가 export 중에서 잡 정의를 식별하는 브랜드. */
+export declare const JOB_BRAND: unique symbol;
+export interface JobDef<Args extends readonly unknown[]> {
+    readonly [JOB_BRAND]: true;
+    /** 잡 이름(해석된 최종값). 미해석 상태에서 접근하면 수리 안내 에러. */
+    readonly name: string;
+    readonly queue: string;
+    readonly options: JobOptions;
+    readonly handler: (...args: Args) => Promise<void> | void;
+    /** 즉시 큐잉. 인자는 handler 시그니처 그대로. */
+    later(...args: Args): Promise<void>;
+    /** 지연 큐잉. '10m'·30_000(ms) 뒤 실행. */
+    in(delay: string | number, ...args: Args): Promise<void>;
+    /** 지정 시각에 실행(Date). 과거면 즉시. */
+    at(when: Date, ...args: Args): Promise<void>;
+    /**
+     * 파일명 기반 이름을 1회 부여한다(파일 로더 전용). 이미 이름이 있으면
+     * 무시한다. 이름을 붙이면서 워커 조회용 레지스트리에도 등록한다. 이
+     * 객체를 그대로 mutate 하므로, 로드 후 `SendWelcomeMail.later()` 가
+     * serve·work 어느 프로세스에서든 동작한다.
+     */
+    assignName(name: string): void;
+}
+/**
+ * enqueue 전송을 설정한다(부팅 시 1회 — 웹서버·워커 공통). 이후 `.later()`
+ * 등이 이 NATS 로 잡을 publish 한다. 잡 스트림은 첫 enqueue 때 보장한다.
+ */
+export declare function configureJobs(nats: GaonNats, tuning?: StreamTuning): void;
+/** 설정 해제(테스트 teardown). */
+export declare function resetJobs(): void;
+/**
+ * 잡을 정의한다. 반환 객체를 `domain/jobs/*.ts` 에서 export 하면 등록이다.
+ * 이름은 옵션으로 주거나(명시), 파일 로더가 파일명에서 채운다.
+ */
+export declare function job<Args extends readonly unknown[]>(handler: (...args: Args) => Promise<void> | void, options?: JobOptions): JobDef<Args>;
+/** 잡을 레지스트리에 등록(워커가 핸들러 조회에 쓴다). 이름 필수. */
+export declare function registerJob<Args extends readonly unknown[]>(def: JobDef<Args>): void;
+/** 등록된 잡 조회(워커). */
+export declare function getJob(name: string): JobDef<never> | undefined;
+/** 등록된 잡의 큐 집합(워커가 컨슈머를 만들 때 쓴다). */
+export declare function registeredQueues(): string[];
+/** 등록된 전 잡(진단·워커). */
+export declare function registeredJobs(): JobDef<never>[];
+/** 값이 잡 정의인가(파일 로더가 export 를 훑을 때). */
+export declare function isJobDef(value: unknown): value is JobDef<readonly unknown[]>;
+/** 저수준 재적재(워커 재시도·CLI retry 공용). notBefore·attempt 를 명시한다. */
+export declare function enqueueRaw(msg: JobMessage): Promise<void>;

package/dist/jobs.js

@@ -0,0 +1,138 @@
+// @gaonjs/async · 잡 레이어 (§7 M7 · line 781~796)
+//
+// 잡은 도메인 소속이다 — `domain/jobs/` 에 파일을 놓으면 등록이고, 어느
+// 앱에서 큐잉하든 같은 워커(`gaon work`)가 처리한다. 모델·서비스와 같은
+// 함수/객체 스타일이다(데코레이터 금지).
+//
+//   export const SendWelcomeMail = job(async (userId: bigint) => { ... },
+//                                      { retries: 3 })
+//   await SendWelcomeMail.later(user.id)      // 즉시 큐잉(인자 타입 추론)
+//   await SendWelcomeMail.in('10m', user.id)  // 지연 실행
+//
+// 전송은 JetStream 이다. enqueue 는 잡 메시지를 큐 subject 로 publish 하고,
+// 워커가 pull 컨슈머로 당겨 처리한다(worker.ts). 지연·재시도는 메시지의
+// notBefore(실행 하한 시각)로 표현하고, 재시도는 attempt 를 올려 재적재한다.
+import { randomUUID } from 'node:crypto';
+import { parseDuration } from './duration.js';
+import { encodePayloadBytes } from './codec.js';
+import { ensureJobsStream, jobSubject } from './streams.js';
+/** 큐 기본 이름. `{ queue }` 미지정 시. */
+export const DEFAULT_QUEUE = 'default';
+// 잡 이름 → 정의. 워커가 수신 메시지의 name 으로 핸들러를 찾는다. enqueue
+// 측은 이 레지스트리가 없어도 되지만(name/queue 만 알면 publish 가능),
+// 워커 측은 반드시 잡 파일을 import 해 여기에 채워야 한다.
+const registry = new Map();
+/** 파일 로더가 export 중에서 잡 정의를 식별하는 브랜드. */
+export const JOB_BRAND = Symbol.for('gaonjs.async.job');
+let runtime;
+/**
+ * enqueue 전송을 설정한다(부팅 시 1회 — 웹서버·워커 공통). 이후 `.later()`
+ * 등이 이 NATS 로 잡을 publish 한다. 잡 스트림은 첫 enqueue 때 보장한다.
+ */
+export function configureJobs(nats, tuning = {}) {
+    runtime = { nats, tuning, ensured: false };
+}
+/** 설정 해제(테스트 teardown). */
+export function resetJobs() {
+    runtime = undefined;
+    registry.clear();
+}
+function requireRuntime() {
+    if (!runtime) {
+        throw new Error(`[@gaonjs/async] 잡 전송이 설정되지 않았습니다.\n` +
+            `→ 부팅 코드에서 configureJobs(await connectNats()) 를 호출하세요\n` +
+            `  (gaon serve·work 는 자동으로 호출합니다).`);
+    }
+    return runtime;
+}
+async function publishJob(msg) {
+    const rt = requireRuntime();
+    if (!rt.ensured) {
+        await ensureJobsStream(rt.nats, rt.tuning);
+        rt.ensured = true;
+    }
+    // msgID = `<잡 id>#<attempt>` → 중복 제거 창 안의 재적재(크래시로 같은
+    // 메시지를 두 번 재처리해 재시도가 두 번 발행되는 경우)를 흡수한다.
+    // attempt 를 포함해 정상 재시도(attempt 증가)는 별개 메시지로 남긴다.
+    await rt.nats.js.publish(jobSubject(msg.queue), encodePayloadBytes(msg), {
+        msgID: `${msg.id}#${msg.attempt}`,
+    });
+}
+function enqueue(name, queue, args, notBefore) {
+    const now = Date.now();
+    return publishJob({
+        id: randomUUID(),
+        name,
+        queue,
+        args,
+        attempt: 0,
+        notBefore: Math.max(now, notBefore),
+        enqueuedAt: now,
+    });
+}
+/**
+ * 잡을 정의한다. 반환 객체를 `domain/jobs/*.ts` 에서 export 하면 등록이다.
+ * 이름은 옵션으로 주거나(명시), 파일 로더가 파일명에서 채운다.
+ */
+export function job(handler, options = {}) {
+    const queue = options.queue ?? DEFAULT_QUEUE;
+    let resolved = options.name ?? '';
+    const def = {
+        [JOB_BRAND]: true,
+        get name() {
+            if (!resolved) {
+                throw new Error(`[@gaonjs/async] 잡 이름이 없습니다.\n` +
+                    `→ job(fn, { name: '...' }) 로 이름을 주거나 domain/jobs/ 에 파일로 두세요.`);
+            }
+            return resolved;
+        },
+        queue,
+        options,
+        handler,
+        later(...args) {
+            return enqueue(this.name, queue, args, Date.now());
+        },
+        in(delay, ...args) {
+            return enqueue(this.name, queue, args, Date.now() + parseDuration(delay));
+        },
+        at(when, ...args) {
+            return enqueue(this.name, queue, args, when.getTime());
+        },
+        assignName(name) {
+            if (resolved)
+                return;
+            resolved = name;
+            registerJob(def);
+        },
+    };
+    if (resolved)
+        registerJob(def);
+    return def;
+}
+/** 잡을 레지스트리에 등록(워커가 핸들러 조회에 쓴다). 이름 필수. */
+export function registerJob(def) {
+    registry.set(def.name, def);
+}
+/** 등록된 잡 조회(워커). */
+export function getJob(name) {
+    return registry.get(name);
+}
+/** 등록된 잡의 큐 집합(워커가 컨슈머를 만들 때 쓴다). */
+export function registeredQueues() {
+    const set = new Set();
+    for (const def of registry.values())
+        set.add(def.queue);
+    return [...set];
+}
+/** 등록된 전 잡(진단·워커). */
+export function registeredJobs() {
+    return [...registry.values()];
+}
+/** 값이 잡 정의인가(파일 로더가 export 를 훑을 때). */
+export function isJobDef(value) {
+    return typeof value === 'object' && value !== null && value[JOB_BRAND] === true;
+}
+/** 저수준 재적재(워커 재시도·CLI retry 공용). notBefore·attempt 를 명시한다. */
+export function enqueueRaw(msg) {
+    return publishJob(msg);
+}

package/dist/listeners.d.ts

@@ -0,0 +1,37 @@
+import type { GaonNats } from './nats.js';
+import { type StreamTuning } from './streams.js';
+export type ListenerEvent = {
+    readonly kind: 'handled';
+    readonly listener: string;
+    readonly event: string;
+} | {
+    readonly kind: 'retrying';
+    readonly listener: string;
+    readonly event: string;
+    readonly attempt: number;
+} | {
+    readonly kind: 'dropped';
+    readonly listener: string;
+    readonly event: string;
+    readonly error: string;
+} | {
+    readonly kind: 'error';
+    readonly error: string;
+};
+export interface ListenersOptions {
+    readonly nats: GaonNats;
+    /** ack 대기(ms). 기본 30000. */
+    readonly ackWaitMs?: number;
+    /** 리스너 최대 재전달(크래시·실패 합산). 기본 6. */
+    readonly maxDeliver?: number;
+    /** graceful drain 상한(ms). 기본 30000. */
+    readonly drainTimeoutMs?: number;
+    readonly tuning?: StreamTuning;
+    onEvent?(e: ListenerEvent): void;
+}
+export interface ListenersHandle {
+    stop(): Promise<void>;
+    readonly inflight: number;
+}
+/** 등록된 리스너들을 이벤트 스트림에 붙여 소비를 시작한다. */
+export declare function runListeners(opts: ListenersOptions): Promise<ListenersHandle>;