@gaonjs/async 0.1.3 → 0.2.1

package/dist/protocol.js

@@ -0,0 +1,66 @@
+// @gaonjs/async · 실시간 와이어 프로토콜 (§7 · errata E-2 2026-07-23)
+//
+// 경로별 메시지 형식을 한곳에 모은다:
+//  1) 클라이언트 ↔ 웹서버 (WebSocket JSON 프레임)
+//  2) 웹서버 → 허브 (프레즌스 명령 · **TCP 지속 연결 · 라인 구분 JSON**)
+//  3) 허브 → 전 웹서버 (프레즌스 델타 브로드캐스트 · NATS pub/sub)
+//  4) 채널 브로드캐스트 (웹서버 ↔ 웹서버 · NATS pub/sub)
+//
+// errata E-2: 웹서버↔허브는 **TCP 지속 연결**이다(소켓 close = 즉시 죽음
+// 감지). NATS 는 broadcast(허브→웹서버 델타)와 KV 영속·리더선출 전용.
+// (구 방식의 NATS request/reply 명령 경로는 HubCommand+TCP 로 대체됐다.)
+import { encodeSegment } from './keys.js';
+// ─── NATS subject 상수 ──────────────────────────────────────────────────
+/** 웹서버 → 허브 프레즌스 명령(허브가 큐 구독). */
+export const HUB_PRESENCE_SUBJECT = 'gaon.hub.presence';
+/** 허브 → 전 서버 프레즌스 델타(채널별). 채널명은 내부에서 인코딩한다. */
+export function presenceEventSubject(channel) {
+    return `gaon.presence.${encodeSegment(channel)}`;
+}
+/** 리더 허브가 자신의 TCP 엔드포인트를 공지하는 KV 버킷·키(멀티호스트 발견). */
+export const HUB_ENDPOINT_BUCKET = 'gaon_hub';
+export const HUB_ENDPOINT_KEY = 'endpoint';
+// ─── TCP 라인 프레이밍 (라인 구분 JSON) ─────────────────────────────────
+/** 값을 개행 종결 JSON 한 줄로 인코딩(TCP 전송 단위). */
+export function encodeLine(value) {
+    return JSON.stringify(value) + '\n';
+}
+/**
+ * TCP 청크를 누적해 완결된 라인(JSON)만 파싱해 내는 디코더를 만든다.
+ * 소켓은 메시지 경계를 보장하지 않으므로(청크 분할·병합) 개행으로 잘라
+ * 완성된 줄만 넘긴다. 파싱 불가한 줄은 건너뛴다.
+ */
+export function createLineDecoder() {
+    let buf = '';
+    return (chunk) => {
+        buf += chunk;
+        const out = [];
+        let idx;
+        while ((idx = buf.indexOf('\n')) >= 0) {
+            const line = buf.slice(0, idx);
+            buf = buf.slice(idx + 1);
+            if (!line.trim())
+                continue;
+            try {
+                out.push(JSON.parse(line));
+            }
+            catch {
+                // 손상 라인 무시(다음 라인부터 정상 복구)
+            }
+        }
+        return out;
+    };
+}
+/** JSON 을 NATS 페이로드(Uint8Array)로. */
+export function encodeJson(value) {
+    return new TextEncoder().encode(JSON.stringify(value));
+}
+/** NATS 페이로드(Uint8Array)를 JSON 으로. 실패 시 undefined. */
+export function decodeJson(bytes) {
+    try {
+        return JSON.parse(new TextDecoder().decode(bytes));
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/runtime.d.ts

@@ -0,0 +1,39 @@
+import type { GaonNats } from './nats.js';
+import type { ChannelDef } from './channel.js';
+import { type PresenceClient } from './presence.js';
+/** 전송 계층이 구현하는 소켓 인터페이스. */
+export interface SocketAdapter {
+    send(text: string): void;
+    close(code?: number, reason?: string): void;
+}
+export interface ChannelRuntimeOptions {
+    readonly nats: GaonNats;
+    /** 이 웹서버 식별자. */
+    readonly server: string;
+    /** 프레즌스 클라이언트(주입). 생략 시 내부 생성. */
+    readonly presence?: PresenceClient;
+    /** 허브 TCP 주소 'host:port'(errata E-2). 생략 시 NATS KV 공지 발견. */
+    readonly hubAddr?: string;
+    /** 프레즌스 ping 주기(ms) — 반열림 백스톱. */
+    readonly heartbeatMs?: number;
+}
+export interface JoinRequest<User = unknown> {
+    readonly channel: string;
+    readonly def: ChannelDef<User>;
+    readonly member: string;
+    readonly user: User | null;
+    readonly query: Readonly<Record<string, string>>;
+    readonly socket: SocketAdapter;
+}
+export interface Connection {
+    /** 클라이언트가 보낸 원시 텍스트 프레임을 처리한다. */
+    receive(raw: string): Promise<void>;
+    /** 연결 종료 — 프레즌스 해제·onLeave·구독 정리. */
+    leave(): Promise<void>;
+}
+export interface ChannelRuntime {
+    /** 인가 실패 시 소켓을 닫고 null 을 반환한다. */
+    join<User>(req: JoinRequest<User>): Promise<Connection | null>;
+    close(): Promise<void>;
+}
+export declare function createChannelRuntime(opts: ChannelRuntimeOptions): Promise<ChannelRuntime>;

package/dist/runtime.js

@@ -0,0 +1,129 @@
+// @gaonjs/async · 채널 런타임 (웹서버 측 · §7)
+//
+// 웹서버(serve 프로세스)마다 하나. 채널 정의(channel())의 훅을 구동하고,
+// 브로드캐스트는 NATS pub/sub 으로 전 인스턴스에 팬아웃하며(별도 어댑터
+// 불필요 §7 line 891), 프레즌스는 허브와 동기화한다. 소켓 전송은 어댑터로
+// 주입받아 전송 계층(@fastify/websocket)과 분리한다 — 런타임 자체는 실
+// NATS 로 소켓 없이도 테스트할 수 있다.
+import { channelSubject } from './keys.js';
+import { encodeJson, decodeJson } from './protocol.js';
+import { createPresenceClient } from './presence.js';
+export async function createChannelRuntime(opts) {
+    const nats = opts.nats;
+    const presence = opts.presence ??
+        (await createPresenceClient({
+            nats,
+            server: opts.server,
+            hubAddr: opts.hubAddr,
+            heartbeatMs: opts.heartbeatMs,
+        }));
+    const ownPresence = !opts.presence;
+    const channels = new Map();
+    const sendFrame = (socket, frame) => {
+        socket.send(JSON.stringify(frame));
+    };
+    const deliverToChannel = (channel, frame) => {
+        const state = channels.get(channel);
+        if (!state)
+            return;
+        for (const c of state.conns)
+            sendFrame(c.socket, frame);
+    };
+    /** 채널 인프라(브로드캐스트·프레즌스 구독)를 필요 시 최초 1회 만든다. */
+    const ensureChannel = (channel) => {
+        const existing = channels.get(channel);
+        if (existing)
+            return existing;
+        // 브로드캐스트: 모든 서버가 같은 subject 를 구독 → 발행 1건이 전
+        // 인스턴스의 로컬 소켓으로 팬아웃(발행자 자신 포함, 중복 없음).
+        const broadcastSub = nats.nc.subscribe(channelSubject(channel));
+        (async () => {
+            for await (const m of broadcastSub) {
+                const env = decodeJson(m.data);
+                if (env)
+                    deliverToChannel(channel, { t: 'msg', data: env.data });
+            }
+        })();
+        // 프레즌스 델타: 허브 방송을 로컬 소켓으로 전달.
+        const unsubPresence = presence.subscribe(channel, (ev) => {
+            if (ev.type === 'join')
+                deliverToChannel(channel, { t: 'presence:join', member: ev.member });
+            else
+                deliverToChannel(channel, { t: 'presence:leave', member: ev.member });
+        });
+        const state = { conns: new Set(), broadcastSub, unsubPresence };
+        channels.set(channel, state);
+        return state;
+    };
+    const teardownIfEmpty = (channel) => {
+        const state = channels.get(channel);
+        if (!state || state.conns.size > 0)
+            return;
+        state.broadcastSub.unsubscribe();
+        state.unsubPresence();
+        channels.delete(channel);
+    };
+    return {
+        async join(req) {
+            // 런타임은 채널을 타입 소거해 다룬다(전송 계층이 User 를 알 필요 없음).
+            const def = req.def;
+            const authCtx = { channel: req.channel, user: req.user, query: req.query };
+            if (def.authorize) {
+                const ok = await def.authorize(authCtx);
+                if (!ok) {
+                    sendFrame(req.socket, { t: 'error', message: '채널 인가 거부' });
+                    req.socket.close(4401, 'unauthorized');
+                    return null;
+                }
+            }
+            const info = def.presenceInfo ? def.presenceInfo(authCtx) : {};
+            const ctx = {
+                channel: req.channel,
+                member: req.member,
+                user: req.user,
+                query: req.query,
+                send: (data) => sendFrame(req.socket, { t: 'msg', data }),
+                broadcast: (data) => {
+                    const env = { data };
+                    nats.nc.publish(channelSubject(req.channel), encodeJson(env));
+                },
+                presence: () => presence.list(req.channel),
+            };
+            const state = ensureChannel(req.channel);
+            const conn = { member: req.member, socket: req.socket, ctx, def };
+            state.conns.add(conn);
+            // 허브에 등록(KV 반영까지 대기) → 초기 스냅샷을 KV 권위에서 읽어 전송.
+            await presence.join(req.channel, req.member, info);
+            const members = await presence.list(req.channel);
+            sendFrame(req.socket, { t: 'joined', channel: req.channel, member: req.member });
+            sendFrame(req.socket, { t: 'presence', members });
+            await def.onJoin?.(ctx);
+            let left = false;
+            return {
+                async receive(raw) {
+                    const msg = decodeJson(new TextEncoder().encode(raw));
+                    if (msg?.t === 'msg')
+                        await def.onMessage?.(ctx, msg.data);
+                },
+                async leave() {
+                    if (left)
+                        return;
+                    left = true;
+                    await presence.leave(req.channel, req.member);
+                    await def.onLeave?.(ctx);
+                    state.conns.delete(conn);
+                    teardownIfEmpty(req.channel);
+                },
+            };
+        },
+        async close() {
+            for (const [, state] of channels) {
+                state.broadcastSub.unsubscribe();
+                state.unsubPresence();
+            }
+            channels.clear();
+            if (ownPresence)
+                await presence.close();
+        },
+    };
+}

package/dist/schedule.d.ts

@@ -0,0 +1,71 @@
+import type { GaonNats } from './nats.js';
+import { type CronMatcher } from './cron.js';
+/** 스케줄 대상(잡). later() 만 있으면 된다 — 순환 의존을 피해 최소 형태로. */
+export interface Schedulable {
+    readonly name: string;
+    later(...args: never[]): Promise<void>;
+}
+interface EveryEntry {
+    readonly kind: 'every';
+    readonly intervalMs: number;
+    readonly job: Schedulable;
+    readonly label: string;
+}
+interface CronEntry {
+    readonly kind: 'cron';
+    readonly matcher: CronMatcher;
+    readonly job: Schedulable;
+    readonly label: string;
+}
+export type ScheduleEntry = EveryEntry | CronEntry;
+/** 하루 중 시각 지정 빌더(`s.daily.at('04:00', Job)`). */
+export interface DailyBuilder {
+    at(hhmm: string, job: Schedulable): void;
+}
+export interface ScheduleBuilder {
+    /** 고정 간격 반복. '10m'·30_000(ms). 스케줄러 시작 후 interval 마다. */
+    every(interval: string | number, job: Schedulable): void;
+    /** 매일 지정 시각(로컬 타임존). 'HH:MM'. */
+    readonly daily: DailyBuilder;
+    /** 크론식(5필드). 탈출구. */
+    cron(expr: string, job: Schedulable): void;
+}
+export interface ScheduleDef {
+    readonly entries: readonly ScheduleEntry[];
+}
+/** 스케줄을 선언한다. 콜백에서 s.every/daily.at/cron 으로 항목을 등록한다. */
+export declare function schedule(build: (s: ScheduleBuilder) => void): ScheduleDef;
+export type SchedulerEvent = {
+    readonly kind: 'leader';
+    readonly leader: boolean;
+} | {
+    readonly kind: 'fired';
+    readonly job: string;
+    readonly label: string;
+} | {
+    readonly kind: 'error';
+    readonly error: string;
+};
+export interface SchedulerOptions {
+    readonly nats: GaonNats;
+    readonly def: ScheduleDef;
+    /** 인스턴스 식별자(리스 값). */
+    readonly id: string;
+    /** 리스 TTL(ms). 기본 leaseLeader 기본(5000). */
+    readonly ttlMs?: number;
+    /** 틱 주기(ms). 기본 1000 — 분 경계 크론을 놓치지 않게 1초 이하 권장. */
+    readonly tickMs?: number;
+    /** 시각 주입(테스트 결정성). 기본 Date.now. */
+    now?(): number;
+    onEvent?(e: SchedulerEvent): void;
+}
+export interface SchedulerHandle {
+    readonly isLeader: boolean;
+    stop(): Promise<void>;
+}
+/**
+ * 스케줄러를 시작한다. 리더로 선출된 인스턴스만 틱을 발행한다. 리더십을
+ * 잃으면 발행을 멈추고, 되찾으면 재개한다(중복 발행 없음).
+ */
+export declare function runScheduler(opts: SchedulerOptions): Promise<SchedulerHandle>;
+export {};

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>;