@gaonjs/async 0.2.0 → 0.2.1

package/dist/__fixtures__/testnats.d.ts

@@ -5,3 +5,5 @@ export declare function createTestNats(name?: string): Promise<GaonNats>;
 export declare function uniqueName(prefix: string): string;
 /** KV 버킷(스트림 KV_<bucket>)을 삭제해 테스트 잔여물을 정리한다. */
 export declare function dropBucket(nats: GaonNats, bucket: string): Promise<void>;
+/** 이름으로 스트림을 삭제한다(잡·DLQ·이벤트 스트림 정리). 없으면 무시. */
+export declare function dropStream(nats: GaonNats, stream: string): Promise<void>;

package/dist/__fixtures__/testnats.js

@@ -19,3 +19,8 @@ export async function dropBucket(nats, bucket) {
     const jsm = await jetstreamManager(nats.nc);
     await jsm.streams.delete(`KV_${bucket}`).catch(() => { });
 }
+/** 이름으로 스트림을 삭제한다(잡·DLQ·이벤트 스트림 정리). 없으면 무시. */
+export async function dropStream(nats, stream) {
+    const jsm = await jetstreamManager(nats.nc);
+    await jsm.streams.delete(stream).catch(() => { });
+}

package/dist/backoff.d.ts

@@ -0,0 +1,20 @@
+/** 기본 백오프 계단(ms): 1s · 5s · 30s · 5m · 1h. (§7 M7 예시 곡선) */
+export declare const DEFAULT_BACKOFF_MS: readonly number[];
+/** 기본 재시도 횟수(최초 실행 제외). 총 시도 = 1 + retries. */
+export declare const DEFAULT_RETRIES = 3;
+export interface BackoffOptions {
+    /** 이산 백오프 계단(ms). 생략 시 DEFAULT_BACKOFF_MS. */
+    readonly curve?: readonly number[];
+    /**
+     * 지터 비율(0~1). 계산된 지연에 ±ratio 범위의 난수를 곱해 흩뜨린다.
+     * 기본 0.2 — 몰림 방지에 충분하되 곡선 형태는 유지한다.
+     */
+    readonly jitter?: number;
+}
+/**
+ * attempt(1-based: 방금 실패한 시도 번호)에 대한 다음 대기(ms)를 계산한다.
+ * attempt=1 → 곡선[0], attempt=2 → 곡선[1] ... 곡선 길이를 넘으면 마지막 값.
+ * 지터는 결정성이 필요 없는 런타임 경로라 Math.random 을 쓴다(테스트는
+ * jitter:0 으로 결정성을 얻는다).
+ */
+export declare function backoffDelayMs(attempt: number, opts?: BackoffOptions): number;

package/dist/backoff.js

@@ -0,0 +1,31 @@
+// @gaonjs/async · 재시도 백오프 곡선 (§7 M7 · 질문 9·10)
+//
+// 설계(§7 line 792)는 재시도를 "NAK 지연 기반 백오프"로 못박았다. 잡이
+// 실패하면 다음 시도까지의 대기를 백오프 곡선에서 뽑아 지연 재적재한다.
+// 곡선은 지수 증가에 지터(jitter)를 섞어 다수 워커가 동시에 재시도해
+// 몰리는 것(thundering herd)을 막는다.
+//
+// 기본 곡선은 이산 계단값이다(1s·5s·30s·5m·1h) — M7 벤치마크로 확정.
+// 짧은 오류는 빠르게, 지속 장애는 성기게 재시도해 자원을 아낀다.
+// attempt 를 넘어서면 마지막 값에서 포화한다.
+/** 기본 백오프 계단(ms): 1s · 5s · 30s · 5m · 1h. (§7 M7 예시 곡선) */
+export const DEFAULT_BACKOFF_MS = [1000, 5000, 30000, 300000, 3600000];
+/** 기본 재시도 횟수(최초 실행 제외). 총 시도 = 1 + retries. */
+export const DEFAULT_RETRIES = 3;
+/**
+ * attempt(1-based: 방금 실패한 시도 번호)에 대한 다음 대기(ms)를 계산한다.
+ * attempt=1 → 곡선[0], attempt=2 → 곡선[1] ... 곡선 길이를 넘으면 마지막 값.
+ * 지터는 결정성이 필요 없는 런타임 경로라 Math.random 을 쓴다(테스트는
+ * jitter:0 으로 결정성을 얻는다).
+ */
+export function backoffDelayMs(attempt, opts = {}) {
+    const curve = opts.curve && opts.curve.length > 0 ? opts.curve : DEFAULT_BACKOFF_MS;
+    const idx = Math.min(Math.max(attempt, 1), curve.length) - 1;
+    const base = curve[idx];
+    const jitter = opts.jitter ?? 0.2;
+    if (jitter <= 0)
+        return base;
+    // 균등 지터: base * (1 ± jitter). 하한 0 보장.
+    const factor = 1 + (Math.random() * 2 - 1) * jitter;
+    return Math.max(0, Math.round(base * factor));
+}

package/dist/codec.d.ts

@@ -0,0 +1,8 @@
+/** 값을 태그드 JSON 문자열로(bigint·Date 왕복 보존). */
+export declare function encodePayload(value: unknown): string;
+/** encodePayload 의 역함수. */
+export declare function decodePayload<T>(text: string): T;
+/** 태그드 JSON 을 NATS 바이트로. */
+export declare function encodePayloadBytes(value: unknown): Uint8Array;
+/** NATS 바이트를 태그드 JSON 으로. */
+export declare function decodePayloadBytes<T>(bytes: Uint8Array): T;

package/dist/codec.js

@@ -0,0 +1,57 @@
+// @gaonjs/async · 잡·이벤트 인자 코덱 (§7 M7)
+//
+// 잡 인자와 이벤트 페이로드는 NATS 를 건너 워커로 전달되므로 JSON 왕복이
+// 필요하다. 그런데 도메인 값에는 JSON 이 기본 지원하지 않는 타입이 있다:
+//  - bigint  — PK 관례(§4.2). JSON.stringify 는 bigint 에서 throw 한다.
+//  - Date    — 타임스탬프 인자.
+// 렌더 경계의 직렬화(M4 SerializedOf)는 문자열로 납작하게 만들지만, 잡은
+// 값 타입을 그대로 복원해야 한다(handler 시그니처가 bigint 를 기대). 그래서
+// 태그드 JSON 으로 왕복 가능한 인코딩을 쓴다.
+function replacer(_key, value) {
+    if (typeof value === 'bigint')
+        return { __gaon: 'bigint', v: value.toString() };
+    return value;
+}
+function isTag(v) {
+    return typeof v === 'object' && v !== null && '__gaon' in v;
+}
+function reviver(_key, value) {
+    if (isTag(value)) {
+        if (value.__gaon === 'bigint')
+            return BigInt(value.v);
+        if (value.__gaon === 'date')
+            return new Date(value.v);
+    }
+    return value;
+}
+// Date 는 toJSON 이 문자열로 바꿔 버려 replacer 가 Date 인지 알 수 없다.
+// 그래서 stringify 전에 Date 를 태그 객체로 치환한다(깊은 순회).
+function tagDates(value) {
+    if (value instanceof Date)
+        return { __gaon: 'date', v: value.toISOString() };
+    if (Array.isArray(value))
+        return value.map(tagDates);
+    if (value && typeof value === 'object') {
+        const out = {};
+        for (const [k, v] of Object.entries(value))
+            out[k] = tagDates(v);
+        return out;
+    }
+    return value;
+}
+/** 값을 태그드 JSON 문자열로(bigint·Date 왕복 보존). */
+export function encodePayload(value) {
+    return JSON.stringify(tagDates(value), replacer);
+}
+/** encodePayload 의 역함수. */
+export function decodePayload(text) {
+    return JSON.parse(text, reviver);
+}
+/** 태그드 JSON 을 NATS 바이트로. */
+export function encodePayloadBytes(value) {
+    return new TextEncoder().encode(encodePayload(value));
+}
+/** NATS 바이트를 태그드 JSON 으로. */
+export function decodePayloadBytes(bytes) {
+    return decodePayload(new TextDecoder().decode(bytes));
+}

package/dist/cron.d.ts

@@ -0,0 +1,7 @@
+export interface CronMatcher {
+    /** 이 Date(로컬 시간)의 분 경계가 크론식과 맞는가. */
+    matches(date: Date): boolean;
+    readonly expr: string;
+}
+/** 5필드 크론식을 매처로 컴파일한다. 형식 오류는 수리 안내 에러로 던진다. */
+export declare function parseCron(expr: string): CronMatcher;

package/dist/cron.js

@@ -0,0 +1,88 @@
+// @gaonjs/async · 최소 크론 파서 (§7 M7 · line 838~849)
+//
+// 표준 5필드 크론(분 시 일 월 요일)의 실용 부분집합을 지원한다: `*`,
+// 숫자, 리스트(`,`), 범위(`-`), 스텝(`*/n` · `a-b/n`). 요일은 0(일)~6(토),
+// 7 도 일요일로 받는다. 초 단위·`?`·`L`·`#` 같은 확장 문법은 v1 범위 밖이다
+// (필요하면 `s.every()` 나 `s.daily.at()` 를 쓰라고 스케줄 API 가 안내한다).
+//
+// 새 런타임 의존을 더하지 않으려 자체 구현한다("만들지 않고 접착한다"의
+// 예외 — cron 라이브러리는 표면적이 크고, 우리에겐 이 부분집합으로 충분하다).
+const MINUTE = { min: 0, max: 59 };
+const HOUR = { min: 0, max: 23 };
+const DOM = { min: 1, max: 31 };
+const MONTH = { min: 1, max: 12 };
+const DOW = { min: 0, max: 7 };
+function parseField(token, field, label, expr) {
+    const out = new Set();
+    for (const part of token.split(',')) {
+        const [rangePart, stepPart] = part.split('/');
+        const step = stepPart ? Number(stepPart) : 1;
+        if (!Number.isInteger(step) || step < 1) {
+            throw cronError(expr, `${label} 스텝이 잘못됐습니다: '${part}'`);
+        }
+        let lo;
+        let hi;
+        if (rangePart === '*') {
+            lo = field.min;
+            hi = field.max;
+        }
+        else if (rangePart.includes('-')) {
+            const [a, b] = rangePart.split('-').map(Number);
+            lo = a;
+            hi = b;
+        }
+        else {
+            lo = Number(rangePart);
+            hi = lo;
+        }
+        if (!Number.isInteger(lo) || !Number.isInteger(hi) || lo < field.min || hi > field.max || lo > hi) {
+            throw cronError(expr, `${label} 값이 범위를 벗어났습니다: '${part}' (허용 ${field.min}~${field.max})`);
+        }
+        for (let v = lo; v <= hi; v += step)
+            out.add(v);
+    }
+    return out;
+}
+function cronError(expr, detail) {
+    return new Error(`[@gaonjs/async] 크론식을 이해할 수 없습니다: '${expr}'\n` +
+        `→ ${detail}\n` +
+        `→ 5필드(분 시 일 월 요일)를 쓰세요 — 예: '0 9 * * 1' (월요일 09:00).\n` +
+        `→ 간단한 반복은 s.every('10m', Job) · s.daily.at('04:00', Job) 가 더 읽기 쉽습니다.`);
+}
+/** 5필드 크론식을 매처로 컴파일한다. 형식 오류는 수리 안내 에러로 던진다. */
+export function parseCron(expr) {
+    const tokens = expr.trim().split(/\s+/);
+    if (tokens.length !== 5) {
+        throw cronError(expr, `필드가 ${tokens.length}개입니다(5개여야 함: 분 시 일 월 요일)`);
+    }
+    const minutes = parseField(tokens[0], MINUTE, '분', expr);
+    const hours = parseField(tokens[1], HOUR, '시', expr);
+    const doms = parseField(tokens[2], DOM, '일', expr);
+    const months = parseField(tokens[3], MONTH, '월', expr);
+    const dowsRaw = parseField(tokens[4], DOW, '요일', expr);
+    // 7 → 0(일요일) 정규화.
+    const dows = new Set([...dowsRaw].map((d) => (d === 7 ? 0 : d)));
+    const domRestricted = tokens[2] !== '*';
+    const dowRestricted = tokens[4] !== '*';
+    return {
+        expr,
+        matches(date) {
+            if (!minutes.has(date.getMinutes()))
+                return false;
+            if (!hours.has(date.getHours()))
+                return false;
+            if (!months.has(date.getMonth() + 1))
+                return false;
+            const domOk = doms.has(date.getDate());
+            const dowOk = dows.has(date.getDay());
+            // 표준 크론 규칙: 일·요일이 둘 다 제한되면 OR(둘 중 하나만 맞아도 실행).
+            if (domRestricted && dowRestricted)
+                return domOk || dowOk;
+            if (domRestricted)
+                return domOk;
+            if (dowRestricted)
+                return dowOk;
+            return true;
+        },
+    };
+}

package/dist/dlq.d.ts

@@ -0,0 +1,18 @@
+import type { GaonNats } from './nats.js';
+import type { DlqRecord } from './worker.js';
+/** DLQ 레코드 + 스트림 시퀀스(삭제·재적재에 필요). */
+export interface DlqEntry extends DlqRecord {
+    readonly seq: number;
+}
+/** DLQ 의 실패 잡을 최신순으로 나열한다(limit 개). */
+export declare function listDlq(nats: GaonNats, limit?: number): Promise<DlqEntry[]>;
+/** id 로 DLQ 레코드를 찾는다(최신 우선). 없으면 undefined. */
+export declare function findDlq(nats: GaonNats, id: string): Promise<DlqEntry | undefined>;
+/**
+ * DLQ 잡을 잡 큐로 재적재한다(attempt 0, 즉시 실행). 성공하면 DLQ 레코드를
+ * 삭제한다. enqueue 전송이 설정돼 있어야 한다(configureJobs) — 미설정이면
+ * 주어진 nats 로 임시 설정한다.
+ */
+export declare function retryDlq(nats: GaonNats, id: string): Promise<DlqEntry>;
+/** DLQ 를 통째로 비운다(운영 정리용). 삭제 개수를 돌려준다. */
+export declare function purgeDlq(nats: GaonNats): Promise<number>;

package/dist/dlq.js

@@ -0,0 +1,70 @@
+// @gaonjs/async · DLQ 조회·재적재 (§7 M7 · line 886~887)
+//
+// 최대 재시도를 소진한 잡은 DLQ 스트림에 레코드로 남는다(worker.ts). 운영자·
+// 개발 대시보드가 이를 훑어보고(`gaon jobs list --failed`) 원인을 고친 뒤
+// 재실행한다(`gaon jobs retry <id>`). 재적재는 잡을 attempt 0 으로 잡 큐에
+// 다시 넣고 DLQ 레코드를 지운다.
+import { randomUUID } from 'node:crypto';
+import { jetstreamManager } from '@nats-io/jetstream';
+import { DLQ_STREAM, DLQ_SUBJECT, ensureDlqStream } from './streams.js';
+import { decodePayloadBytes } from './codec.js';
+import { enqueueRaw, configureJobs } from './jobs.js';
+/** DLQ 의 실패 잡을 최신순으로 나열한다(limit 개). */
+export async function listDlq(nats, limit = 100) {
+    await ensureDlqStream(nats);
+    const jsm = await jetstreamManager(nats.nc);
+    const info = await jsm.streams.info(DLQ_STREAM);
+    const last = info.state.last_seq;
+    const first = info.state.first_seq;
+    const out = [];
+    for (let seq = last; seq >= first && out.length < limit; seq--) {
+        const stored = await jsm.streams.getMessage(DLQ_STREAM, { seq }).catch(() => null);
+        if (!stored)
+            continue;
+        const rec = decodePayloadBytes(stored.data);
+        out.push({ ...rec, seq: stored.seq });
+    }
+    return out;
+}
+/** id 로 DLQ 레코드를 찾는다(최신 우선). 없으면 undefined. */
+export async function findDlq(nats, id) {
+    const all = await listDlq(nats, 1000);
+    return all.find((e) => e.id === id);
+}
+/**
+ * DLQ 잡을 잡 큐로 재적재한다(attempt 0, 즉시 실행). 성공하면 DLQ 레코드를
+ * 삭제한다. enqueue 전송이 설정돼 있어야 한다(configureJobs) — 미설정이면
+ * 주어진 nats 로 임시 설정한다.
+ */
+export async function retryDlq(nats, id) {
+    const entry = await findDlq(nats, id);
+    if (!entry) {
+        throw new Error(`[@gaonjs/async] DLQ 에 id='${id}' 인 잡이 없습니다.\n` +
+            `→ gaon jobs list --failed 로 현재 목록을 확인하세요.`);
+    }
+    configureJobs(nats);
+    const now = Date.now();
+    const msg = {
+        id: randomUUID(),
+        name: entry.name,
+        queue: entry.queue,
+        args: entry.args,
+        attempt: 0,
+        notBefore: now,
+        enqueuedAt: now,
+    };
+    await enqueueRaw(msg);
+    // 재적재에 성공했으니 DLQ 원본을 지운다(재적재 후 실패해도 다시 DLQ 로 온다).
+    const jsm = await jetstreamManager(nats.nc);
+    await jsm.streams.deleteMessage(DLQ_STREAM, entry.seq).catch(() => { });
+    return entry;
+}
+/** DLQ 를 통째로 비운다(운영 정리용). 삭제 개수를 돌려준다. */
+export async function purgeDlq(nats) {
+    await ensureDlqStream(nats);
+    const jsm = await jetstreamManager(nats.nc);
+    const info = await jsm.streams.info(DLQ_STREAM);
+    const n = info.state.messages;
+    await jsm.streams.purge(DLQ_STREAM, { filter: DLQ_SUBJECT });
+    return Number(n);
+}

package/dist/duration.d.ts

@@ -0,0 +1,5 @@
+/**
+ * '10m' → 600000. 파싱 실패는 수리 안내를 담은 에러로 던진다(§7.5.3).
+ * 숫자(number)를 그대로 주면 ms 로 통과시킨다.
+ */
+export declare function parseDuration(value: string | number): number;

package/dist/duration.js

@@ -0,0 +1,33 @@
+// @gaonjs/async · 사람이 읽는 기간 문자열 (§7 M7)
+//
+// 잡 지연(`.in('10m', ...)`)과 스케줄(`s.every('10m', ...)`)에서 크론 문법을
+// 몰라도 되게 하는 자연스러운 기간 표기다(§7 line 838 "크론 문법을 몰라도
+// 되는 자연스러운 API"). 단위: ms · s · m · h · d. 숫자만 오면 ms 로 본다.
+const UNIT_MS = {
+    ms: 1,
+    s: 1000,
+    m: 60000,
+    h: 3600000,
+    d: 86400000,
+};
+const PATTERN = /^(\d+(?:\.\d+)?)\s*(ms|s|m|h|d)?$/;
+/**
+ * '10m' → 600000. 파싱 실패는 수리 안내를 담은 에러로 던진다(§7.5.3).
+ * 숫자(number)를 그대로 주면 ms 로 통과시킨다.
+ */
+export function parseDuration(value) {
+    if (typeof value === 'number') {
+        if (!Number.isFinite(value) || value < 0) {
+            throw new Error(`[@gaonjs/async] 기간은 0 이상의 유한수여야 합니다: ${value}`);
+        }
+        return value;
+    }
+    const m = PATTERN.exec(value.trim());
+    if (!m) {
+        throw new Error(`[@gaonjs/async] 기간 형식을 이해할 수 없습니다: '${value}'\n` +
+            `→ '10m' · '30s' · '1h' · '2d' · '500ms' 처럼 쓰거나 숫자(ms)를 주세요.`);
+    }
+    const n = Number(m[1]);
+    const unit = m[2] ?? 'ms';
+    return Math.round(n * UNIT_MS[unit]);
+}

package/dist/events.d.ts

@@ -0,0 +1,45 @@
+import type { GaonNats } from './nats.js';
+import { type StreamTuning } from './streams.js';
+/** shape 의 컬럼 정의에서 페이로드 타입을 뽑는다(각 컬럼의 _type). */
+export type PayloadOf<Shape extends Record<string, {
+    readonly _type: unknown;
+}>> = {
+    [K in keyof Shape]: Shape[K]['_type'];
+};
+export interface EventDef<Payload> {
+    readonly name: string;
+    /** 이벤트를 발행한다. 트랜잭션 안이면 아웃박스로, 밖이면 즉시 NATS 로. */
+    emit(payload: Payload): Promise<void>;
+}
+/** 파일 로더가 export 중에서 리스너를 식별하는 브랜드. */
+export declare const LISTENER_BRAND: unique symbol;
+/** 리스너(구독자). 워커가 이벤트명별 durable 컨슈머로 소비한다. */
+export interface Listener<Payload = unknown> {
+    readonly [LISTENER_BRAND]: true;
+    readonly id: string;
+    readonly eventName: string;
+    readonly handler: (payload: Payload) => Promise<void> | void;
+}
+/** emit 전송을 설정한다(부팅 시 1회). */
+export declare function configureEvents(nats: GaonNats, tuning?: StreamTuning): void;
+export declare function resetEvents(): void;
+/** 이벤트를 정의한다. name 은 안정적 식별자(subject·durable 의 근간). */
+export declare function event<Shape extends Record<string, {
+    readonly _type: unknown;
+}>>(name: string, _shape: Shape): EventDef<PayloadOf<Shape>>;
+/**
+ * 이벤트를 구독한다. 반환값을 `domain/listeners/*.ts` 에서 export 하면 등록.
+ * id 는 durable 컨슈머 이름의 근간이라 안정적이어야 한다(파일 로더가
+ * 파일명에서 채운다). 미지정 시 이벤트명 + 순번으로 임시 부여한다.
+ */
+export declare function on<Payload>(def: EventDef<Payload>, handler: (payload: Payload) => Promise<void> | void, opts?: {
+    id?: string;
+}): Listener<Payload>;
+/** 값이 리스너인가(파일 로더가 export 를 훑을 때). */
+export declare function isListener(value: unknown): value is Listener;
+/** 리스너의 id 를 파일명 기반으로 다시 부여해 재등록(로더용 · durable 안정화). */
+export declare function reidentifyListener(listener: Listener, id: string): void;
+/** 등록된 리스너 전체(워커). */
+export declare function registeredListeners(): Listener[];
+/** 저수준 발행(아웃박스 릴레이가 subject 로 직접 publish). */
+export declare function publishToSubject(subject: string, payload: unknown, id: string): Promise<void>;

package/dist/events.js

@@ -0,0 +1,104 @@
+// @gaonjs/async · 이벤트 버스 (§7 M7 · line 798~826)
+//
+// 이벤트는 `domain/events/` 에 정의하고 구독자는 `domain/listeners/` 에
+// 파일로 둔다(파일=등록). 발행자는 누가 듣는지 모른다(결합 제거). 전송은
+// JetStream 이라 영속·at-least-once — 리스너는 멱등하게 짜는 것이 관례다.
+//
+//   export const PostPublished = event('post.published', {
+//     postId: t.bigint(), publisherId: t.bigint(),
+//   })
+//   await PostPublished.emit({ postId: post.id, publisherId: user.id })
+//
+//   export default on(PostPublished, async ({ postId, publisherId }) => { ... })
+//
+// 페이로드 타입은 shape 의 컬럼 정의(`t.bigint()` 등)에서 구조적으로
+// 추론한다 — 각 컬럼은 `_type` 을 노출하므로 @gaonjs/data 를 런타임으로
+// 끌어오지 않고도(구조적 타이핑) 페이로드 모양이 끝까지 흐른다.
+//
+// 트랜잭션 안에서 emit 하면 같은 트랜잭션으로 아웃박스에 적재된다(outbox.ts).
+// 트랜잭션 밖 emit 은 즉시 발행한다. 개발자에겐 이 분기가 보이지 않는다.
+import { randomUUID } from 'node:crypto';
+import { eventSubject, ensureEventsStream } from './streams.js';
+import { encodePayloadBytes } from './codec.js';
+import { currentOutbox } from './outboxContext.js';
+/** 파일 로더가 export 중에서 리스너를 식별하는 브랜드. */
+export const LISTENER_BRAND = Symbol.for('gaonjs.async.listener');
+let runtime;
+/** emit 전송을 설정한다(부팅 시 1회). */
+export function configureEvents(nats, tuning = {}) {
+    runtime = { nats, tuning, ensured: false };
+}
+export function resetEvents() {
+    runtime = undefined;
+    listeners.length = 0;
+}
+function requireRuntime() {
+    if (!runtime) {
+        throw new Error(`[@gaonjs/async] 이벤트 전송이 설정되지 않았습니다.\n` +
+            `→ 부팅 코드에서 configureEvents(await connectNats()) 를 호출하세요.`);
+    }
+    return runtime;
+}
+async function publishEvent(name, payload, id) {
+    const rt = requireRuntime();
+    if (!rt.ensured) {
+        await ensureEventsStream(rt.nats, rt.tuning);
+        rt.ensured = true;
+    }
+    await rt.nats.js.publish(eventSubject(name), encodePayloadBytes(payload), { msgID: id });
+}
+/** 이벤트를 정의한다. name 은 안정적 식별자(subject·durable 의 근간). */
+export function event(name, _shape) {
+    return {
+        name,
+        async emit(payload) {
+            const outbox = currentOutbox();
+            if (outbox) {
+                // 트랜잭션 안 — 같은 트랜잭션으로 아웃박스에 적재(이중 쓰기 방지).
+                await outbox.stage(eventSubject(name), payload);
+            }
+            else {
+                await publishEvent(name, payload, randomUUID());
+            }
+        },
+    };
+}
+// 리스너 레지스트리(워커가 컨슈머를 만들 때 훑는다).
+const listeners = [];
+/**
+ * 이벤트를 구독한다. 반환값을 `domain/listeners/*.ts` 에서 export 하면 등록.
+ * id 는 durable 컨슈머 이름의 근간이라 안정적이어야 한다(파일 로더가
+ * 파일명에서 채운다). 미지정 시 이벤트명 + 순번으로 임시 부여한다.
+ */
+export function on(def, handler, opts = {}) {
+    const id = opts.id ?? `${def.name}#${listeners.length}`;
+    const listener = { [LISTENER_BRAND]: true, id, eventName: def.name, handler };
+    listeners.push(listener);
+    return listener;
+}
+/** 값이 리스너인가(파일 로더가 export 를 훑을 때). */
+export function isListener(value) {
+    return (typeof value === 'object' && value !== null && value[LISTENER_BRAND] === true);
+}
+/** 리스너의 id 를 파일명 기반으로 다시 부여해 재등록(로더용 · durable 안정화). */
+export function reidentifyListener(listener, id) {
+    const idx = listeners.indexOf(listener);
+    const renamed = { ...listener, id };
+    if (idx >= 0)
+        listeners[idx] = renamed;
+    else
+        listeners.push(renamed);
+}
+/** 등록된 리스너 전체(워커). */
+export function registeredListeners() {
+    return [...listeners];
+}
+/** 저수준 발행(아웃박스 릴레이가 subject 로 직접 publish). */
+export async function publishToSubject(subject, payload, id) {
+    const rt = requireRuntime();
+    if (!rt.ensured) {
+        await ensureEventsStream(rt.nats, rt.tuning);
+        rt.ensured = true;
+    }
+    await rt.nats.js.publish(subject, encodePayloadBytes(payload), { msgID: id });
+}

package/dist/hub.d.ts

@@ -5,21 +5,29 @@ export interface HubOptions {
     readonly id: string;
     /** 리스 TTL(ms). 기본 5000. */
     readonly ttlMs?: number;
-    /** 멤버 만료 임계(ms) — 이 시간 넘게 하트비트 없으면 leave 처리. 기본 30000. */
-    readonly memberTimeoutMs?: number;
-    /** 만료 스윕 주기(ms). 기본 5000. */
+    /** TCP 리슨 포트. 기본 4001(env GAON_HUB_PORT). */
+    readonly port?: number;
+    /** TCP 리슨 호스트. 기본 0.0.0.0. */
+    readonly host?: string;
+    /** 멀티호스트 발견용으로 KV 에 공지할 도달 주소(host:port). 기본 127.0.0.1:port. */
+    readonly advertiseAddr?: string;
+    /** 소켓 무활동 임계(ms) — 이 시간 넘게 명령/ping 없으면 반열림으로 보고 끊는다. 기본 10000. */
+    readonly pingTimeoutMs?: number;
+    /** 무활동·회수 스윕 주기(ms). 기본 2000. */
     readonly sweepMs?: number;
+    /** 재접속 안 되는 복원 서버를 회수하기까지의 유예(ms). 기본 15000. */
+    readonly reclaimGraceMs?: number;
     /** 리더십·상태 통지(옵션). */
     onState?(state: {
         leader: boolean;
     }): void;
+    /** 배경 에러 통지(옵션). */
+    onError?(err: Error): void;
 }
 export interface HubHandle {
     readonly isLeader: boolean;
+    /** 현재 리더가 리슨 중인 TCP 포트(테스트·디버깅용). 리더 아니면 undefined. */
+    readonly port: number | undefined;
     stop(): Promise<void>;
 }
-/**
- * 허브를 시작한다. 리더가 되기 전에는 대기하고, 리더가 되면 프레즌스
- * 명령 구독·KV 권위 갱신·델타 중계·만료 스윕을 켠다.
- */
 export declare function runHub(opts: HubOptions): Promise<HubHandle>;