@gaonjs/async 0.2.0 → 0.2.1

package/dist/listeners.js

@@ -0,0 +1,89 @@
+// @gaonjs/async · 리스너 소비 (§7 M7 · line 798~826)
+//
+// 워커(`gaon work`)가 등록된 리스너마다 이벤트 스트림에 durable 컨슈머를
+// 붙여 소비한다. 리스너 id 가 durable 이름의 근간이라, 재시작해도 같은
+// 지점부터 이어 받는다(중복 배달 가능 — 리스너는 멱등 권장).
+//
+// 이벤트는 알림성이라 잡보다 단순하게 다룬다: 성공→ack, 실패→백오프 후
+// 재전달(nak), max_deliver 소진→폐기(term, 로깅). 잡 같은 DLQ 는 두지 않되
+// 재시도는 준다.
+import { jetstreamManager } from '@nats-io/jetstream';
+import { EVENTS_STREAM, eventSubject, listenerConsumerName, toNanos, ensureEventsStream, } from './streams.js';
+import { decodePayloadBytes } from './codec.js';
+import { backoffDelayMs } from './backoff.js';
+import { registeredListeners } from './events.js';
+const DEFAULT_ACK_WAIT_MS = 30000;
+const DEFAULT_MAX_DELIVER = 6;
+const DEFAULT_DRAIN_MS = 30000;
+/** 등록된 리스너들을 이벤트 스트림에 붙여 소비를 시작한다. */
+export async function runListeners(opts) {
+    const ackWaitMs = opts.ackWaitMs ?? DEFAULT_ACK_WAIT_MS;
+    const maxDeliver = opts.maxDeliver ?? DEFAULT_MAX_DELIVER;
+    const drainTimeoutMs = opts.drainTimeoutMs ?? DEFAULT_DRAIN_MS;
+    const emit = (e) => opts.onEvent?.(e);
+    await ensureEventsStream(opts.nats, opts.tuning);
+    const jsm = await jetstreamManager(opts.nats.nc);
+    const listeners = registeredListeners();
+    const closers = [];
+    const inflightAll = new Set();
+    for (const listener of listeners) {
+        const durable = listenerConsumerName(listener.id);
+        await jsm.consumers.add(EVENTS_STREAM, {
+            durable_name: durable,
+            filter_subject: eventSubject(listener.eventName),
+            ack_policy: 'explicit',
+            ack_wait: toNanos(ackWaitMs),
+            max_deliver: maxDeliver,
+        });
+        const handle = async (m) => {
+            const attempt = m.info.deliveryCount;
+            try {
+                const payload = decodePayloadBytes(m.data);
+                await listener.handler(payload);
+                m.ack();
+                emit({ kind: 'handled', listener: listener.id, event: listener.eventName });
+            }
+            catch (err) {
+                const error = err instanceof Error ? err.message : String(err);
+                if (attempt < maxDeliver) {
+                    m.nak(backoffDelayMs(attempt, { jitter: 0.2 }));
+                    emit({ kind: 'retrying', listener: listener.id, event: listener.eventName, attempt });
+                }
+                else {
+                    m.term();
+                    emit({ kind: 'dropped', listener: listener.id, event: listener.eventName, error });
+                }
+            }
+        };
+        const consumer = await opts.nats.js.consumers.get(EVENTS_STREAM, durable);
+        const messages = await consumer.consume({ max_messages: 1 });
+        const loop = (async () => {
+            for await (const m of messages) {
+                const p = handle(m).finally(() => inflightAll.delete(p));
+                inflightAll.add(p);
+                await Promise.race(inflightAll);
+            }
+        })();
+        closers.push(async () => {
+            messages.stop();
+            await loop.catch(() => { });
+        });
+    }
+    let stopped = false;
+    return {
+        get inflight() {
+            return inflightAll.size;
+        },
+        async stop() {
+            if (stopped)
+                return;
+            stopped = true;
+            for (const close of closers)
+                await close();
+            const deadline = Date.now() + drainTimeoutMs;
+            while (inflightAll.size > 0 && Date.now() < deadline) {
+                await Promise.race([...inflightAll, new Promise((r) => setTimeout(r, 200))]);
+            }
+        },
+    };
+}

package/dist/nats.d.ts

@@ -15,6 +15,8 @@ export interface GaonNats {
     readonly kvm: Kvm;
     /** 이름있는 KV 버킷을 열거나(없으면) 만든다. */
     kv(bucket: string, opts?: Partial<KvOptions>): Promise<KV>;
+    /** 이름으로 JetStream 스트림을 삭제한다(없으면 무시). 운영 리셋·테스트 정리용. */
+    deleteStream(name: string): Promise<void>;
     /** 처리 중 메시지를 흘려보내고 연결을 닫는다(graceful). */
     close(): Promise<void>;
 }

package/dist/nats.js

@@ -8,7 +8,7 @@
 // 띄우는 NATS 다. 이 저장소의 테스트 인프라는 mega-nats(4222) 회피용으로
 // 4223 을 쓰므로 `GAON_NATS_URL` 로 재지정한다(§9 테스트 픽스처).
 import { connect } from '@nats-io/transport-node';
-import { jetstream } from '@nats-io/jetstream';
+import { jetstream, jetstreamManager } from '@nats-io/jetstream';
 import { Kvm } from '@nats-io/kv';
 function resolveServers(opts) {
     if (opts.servers)
@@ -43,6 +43,10 @@ export async function connectNats(opts = {}) {
             // 최초 생성 시에만 적용된다.
             return kvm.create(bucket, kvOpts);
         },
+        async deleteStream(name) {
+            const jsm = await jetstreamManager(nc);
+            await jsm.streams.delete(name).catch(() => { });
+        },
         async close() {
             // drain 은 처리 중 메시지를 흘려보내고 닫는다. 이미 닫히는 중이거나
             // in-flight 요청이 끊겨 throw 하면 강제 close 로 마무리한다.

package/dist/outbox.d.ts

@@ -0,0 +1,34 @@
+import type { Kysely, Transaction } from 'kysely';
+export declare const OUTBOX_TABLE = "_gaon_outbox";
+/**
+ * `_gaon_outbox` 테이블을 보장한다(CREATE TABLE IF NOT EXISTS). id 는 클라이언트
+ * 생성 UUID 라 dialect 별 auto-increment 차이를 피한다. created_at 은 코드에서
+ * 넣어 dialect default 함수 의존을 없앤다.
+ */
+export declare function ensureOutboxTable(db: Kysely<any>): Promise<void>;
+/**
+ * 서비스 트랜잭션을 연다. 이 안에서의 emit 은 같은 트랜잭션으로 아웃박스에
+ * 적재된다(트랜잭션 밖 emit 은 즉시 발행). fn 이 throw 하면 롤백 —
+ * 비즈니스 쓰기와 아웃박스 적재가 함께 취소돼 정합이 유지된다.
+ */
+export declare function runInTransaction<T>(db: Kysely<any>, fn: (trx: Transaction<any>) => Promise<T>): Promise<T>;
+export interface RelayOptions {
+    /** 한 번에 처리할 최대 행 수. 기본 100. */
+    readonly batchSize?: number;
+    /** 폴링 주기(ms). 기본 1000. */
+    readonly pollMs?: number;
+    /** 진행 통지(로깅·테스트). */
+    onError?(err: Error): void;
+    onRelayed?(count: number): void;
+}
+export interface RelayHandle {
+    stop(): Promise<void>;
+    /** 한 번 즉시 폴링(테스트·부팅 직후 소진용). 발행 건수를 돌려준다. */
+    drainOnce(): Promise<number>;
+}
+/**
+ * 아웃박스 릴레이를 시작한다. 미발행 행을 폴링해 NATS 로 발행하고 표시한다.
+ * SKIP LOCKED 로 잠긴 행을 건너뛰어 여러 릴레이가 같은 행을 두 번 잡지
+ * 않는다(중복은 at-least-once 로 허용되지만 낭비를 줄인다).
+ */
+export declare function runOutboxRelay(db: Kysely<any>, opts?: RelayOptions): RelayHandle;

package/dist/outbox.js

@@ -0,0 +1,130 @@
+// @gaonjs/async · 아웃박스 패턴 (§7 M7 · line 828~836 · v1 코어 내장)
+//
+// 이중 쓰기(dual-write) 문제 해결: 서비스 트랜잭션이 커밋됐는데 이벤트 발행이
+// 유실되는 일을 막는다. 트랜잭션 안 emit 은 같은 트랜잭션으로 `_gaon_outbox`
+// 에 적재되고(runInTransaction + outboxContext), 백그라운드 릴레이(단순 폴링)가
+// 미발행 행을 NATS 로 발행한 뒤 발행 표시한다. **at-least-once** — 발행 후
+// 표시 사이에 죽으면 다음 폴링이 재발행하고, msgID 중복 제거가 흡수한다.
+//
+// DB 결합을 피하려 Kysely 핸들을 주입받는다(async→data 의존 없음). 테이블은
+// 프레임웍 내부용이라 사용자 스키마 diff 밖에서 ensureOutboxTable 로 보장한다.
+import { randomUUID } from 'node:crypto';
+import { runWithOutbox } from './outboxContext.js';
+import { encodePayload, decodePayload } from './codec.js';
+import { publishToSubject } from './events.js';
+export const OUTBOX_TABLE = '_gaon_outbox';
+/**
+ * `_gaon_outbox` 테이블을 보장한다(CREATE TABLE IF NOT EXISTS). id 는 클라이언트
+ * 생성 UUID 라 dialect 별 auto-increment 차이를 피한다. created_at 은 코드에서
+ * 넣어 dialect default 함수 의존을 없앤다.
+ */
+export async function ensureOutboxTable(db) {
+    await db.schema
+        .createTable(OUTBOX_TABLE)
+        .ifNotExists()
+        .addColumn('id', 'varchar(36)', (c) => c.primaryKey())
+        .addColumn('subject', 'varchar(255)', (c) => c.notNull())
+        .addColumn('payload', 'text', (c) => c.notNull())
+        .addColumn('created_at', 'timestamp', (c) => c.notNull())
+        .addColumn('published_at', 'timestamp')
+        .execute();
+    // 미발행 행 조회를 빠르게(published_at IS NULL 스캔).
+    await db.schema
+        .createIndex(`${OUTBOX_TABLE}_unpublished`)
+        .ifNotExists()
+        .on(OUTBOX_TABLE)
+        .column('published_at')
+        .execute()
+        .catch(() => { });
+}
+/** 트랜잭션에 묶인 stager — 같은 트랜잭션으로 outbox 행을 insert 한다. */
+function makeStager(trx) {
+    return {
+        async stage(subject, payload) {
+            await trx
+                .insertInto(OUTBOX_TABLE)
+                .values({
+                id: randomUUID(),
+                subject,
+                payload: encodePayload(payload),
+                created_at: new Date(),
+                published_at: null,
+            })
+                .execute();
+        },
+    };
+}
+/**
+ * 서비스 트랜잭션을 연다. 이 안에서의 emit 은 같은 트랜잭션으로 아웃박스에
+ * 적재된다(트랜잭션 밖 emit 은 즉시 발행). fn 이 throw 하면 롤백 —
+ * 비즈니스 쓰기와 아웃박스 적재가 함께 취소돼 정합이 유지된다.
+ */
+export function runInTransaction(db, fn) {
+    return db.transaction().execute((trx) => runWithOutbox(makeStager(trx), () => fn(trx)));
+}
+const DEFAULT_BATCH = 100;
+const DEFAULT_POLL_MS = 1000;
+/**
+ * 아웃박스 릴레이를 시작한다. 미발행 행을 폴링해 NATS 로 발행하고 표시한다.
+ * SKIP LOCKED 로 잠긴 행을 건너뛰어 여러 릴레이가 같은 행을 두 번 잡지
+ * 않는다(중복은 at-least-once 로 허용되지만 낭비를 줄인다).
+ */
+export function runOutboxRelay(db, opts = {}) {
+    const batchSize = opts.batchSize ?? DEFAULT_BATCH;
+    const pollMs = opts.pollMs ?? DEFAULT_POLL_MS;
+    let stopped = false;
+    let timer;
+    const relayBatch = async () => {
+        // 미발행 행을 트랜잭션 안에서 잠그고(SKIP LOCKED) 발행 후 표시한다.
+        // 발행(NATS)은 트랜잭션 밖 부수효과라, 표시 커밋 전에 죽으면 재발행된다
+        // (at-least-once). msgID=행 id 로 이벤트 스트림에서 중복 제거된다.
+        const rows = await db.transaction().execute(async (trx) => {
+            const locked = (await trx
+                .selectFrom(OUTBOX_TABLE)
+                .selectAll()
+                .where('published_at', 'is', null)
+                .orderBy('created_at')
+                .limit(batchSize)
+                .forUpdate()
+                .skipLocked()
+                .execute());
+            for (const row of locked) {
+                await publishToSubject(row.subject, decodePayload(row.payload), row.id);
+                await trx
+                    .updateTable(OUTBOX_TABLE)
+                    .set({ published_at: new Date() })
+                    .where('id', '=', row.id)
+                    .execute();
+            }
+            return locked;
+        });
+        if (rows.length > 0)
+            opts.onRelayed?.(rows.length);
+        return rows.length;
+    };
+    const tick = async () => {
+        try {
+            // 밀린 행이 있으면 배치를 연달아 비운다(폴링 지연 없이 소진).
+            let n = 0;
+            do {
+                n = await relayBatch();
+            } while (n >= batchSize && !stopped);
+        }
+        catch (err) {
+            opts.onError?.(err instanceof Error ? err : new Error(String(err)));
+        }
+        finally {
+            if (!stopped)
+                timer = setTimeout(() => void tick(), pollMs);
+        }
+    };
+    void tick();
+    return {
+        async stop() {
+            stopped = true;
+            if (timer)
+                clearTimeout(timer);
+        },
+        drainOnce: relayBatch,
+    };
+}

package/dist/outboxContext.d.ts

@@ -0,0 +1,8 @@
+/** 트랜잭션에 묶인 아웃박스 적재기. 같은 트랜잭션으로 outbox 행을 쓴다. */
+export interface OutboxStager {
+    stage(subject: string, payload: unknown): Promise<void>;
+}
+/** 현재 활성 아웃박스 stager(트랜잭션 안일 때만). 없으면 undefined. */
+export declare function currentOutbox(): OutboxStager | undefined;
+/** stager 를 문맥에 세우고 fn 을 실행한다(트랜잭션 런타임이 호출). */
+export declare function runWithOutbox<T>(stager: OutboxStager, fn: () => Promise<T>): Promise<T>;

package/dist/outboxContext.js

@@ -0,0 +1,16 @@
+// @gaonjs/async · 아웃박스 트랜잭션 컨텍스트 (§7 M7 · line 828~836)
+//
+// emit() 이 "지금 트랜잭션 안인가"를 알아야 아웃박스로 적재할지 즉시 발행할지
+// 정한다. 스택을 타고 내려가는 이 문맥을 AsyncLocalStorage 로 전달한다 —
+// 서비스 트랜잭션이 열리면 트랜잭션에 묶인 stager 를 세우고, 그 안에서의
+// emit 은 같은 트랜잭션으로 _gaon_outbox 에 적재된다. 개발자에겐 보이지 않는다.
+import { AsyncLocalStorage } from 'node:async_hooks';
+const storage = new AsyncLocalStorage();
+/** 현재 활성 아웃박스 stager(트랜잭션 안일 때만). 없으면 undefined. */
+export function currentOutbox() {
+    return storage.getStore();
+}
+/** stager 를 문맥에 세우고 fn 을 실행한다(트랜잭션 런타임이 호출). */
+export function runWithOutbox(stager, fn) {
+    return storage.run(stager, fn);
+}

package/dist/presence.d.ts

@@ -4,19 +4,22 @@ import { type PresenceEvent } from './protocol.js';
 export declare const PRESENCE_BUCKET = "gaon_presence";
 export interface PresenceClientOptions {
     readonly nats: GaonNats;
-    /** 이 웹서버 식별자(하트비트·디버깅). */
+    /** 이 웹서버 식별자(허브가 서버→멤버 매핑에 사용). */
     readonly server: string;
-    /** 하트비트 주기(ms). 기본 10000. 허브 만료 임계의 1/3 이하 권장. */
+    /** 허브 TCP 주소 'host:port'. 생략 시 NATS KV 에 공지된 리더 엔드포인트를 발견. */
+    readonly hubAddr?: string;
+    /** ping 주기(ms). 반열림 감지 백스톱. 기본 3000(허브 pingTimeout 의 1/3 이하). */
     readonly heartbeatMs?: number;
-    /** 허브 응답 대기(ms). 기본 2000. 리더 부재(failover) 시 타임아웃. */
-    readonly requestTimeoutMs?: number;
+    /** 재접속 백오프 최소·최대(ms). 기본 250·2000. */
+    readonly reconnectMinMs?: number;
+    readonly reconnectMaxMs?: number;
 }
 export interface PresenceClient {
     join(channel: string, member: string, info: Record<string, unknown>): Promise<void>;
     leave(channel: string, member: string): Promise<void>;
-    /** 채널의 현재 접속자 목록(허브 KV 권위 · 전 서버 동일). */
+    /** 채널의 현재 접속자 목록(허브 KV 권위 ∪ 로컬 멤버). */
     list(channel: string): Promise<PresenceMember[]>;
-    /** 채널 프레즌스 델타 구독. 반환 함수로 해지. */
+    /** 채널 프레즌스 델타 구독(허브가 NATS 로 broadcast). 반환 함수로 해지. */
     subscribe(channel: string, onEvent: (e: PresenceEvent) => void): () => void;
     close(): Promise<void>;
 }

package/dist/protocol.d.ts

@@ -42,6 +42,26 @@ export type PresenceCommand = {
     readonly member: string;
     readonly server: string;
 };
+export type HubCommand = {
+    readonly op: 'register';
+    readonly server: string;
+} | {
+    readonly op: 'join';
+    readonly channel: string;
+    readonly member: string;
+    readonly info: Record<string, unknown>;
+} | {
+    readonly op: 'leave';
+    readonly channel: string;
+    readonly member: string;
+} | {
+    readonly op: 'synced';
+} | {
+    readonly op: 'unregister';
+    readonly server: string;
+} | {
+    readonly op: 'ping';
+};
 export type PresenceEvent = {
     readonly type: 'join';
     readonly channel: string;
@@ -59,6 +79,17 @@ export interface BroadcastEnvelope {
 export declare const HUB_PRESENCE_SUBJECT = "gaon.hub.presence";
 /** 허브 → 전 서버 프레즌스 델타(채널별). 채널명은 내부에서 인코딩한다. */
 export declare function presenceEventSubject(channel: string): string;
+/** 리더 허브가 자신의 TCP 엔드포인트를 공지하는 KV 버킷·키(멀티호스트 발견). */
+export declare const HUB_ENDPOINT_BUCKET = "gaon_hub";
+export declare const HUB_ENDPOINT_KEY = "endpoint";
+/** 값을 개행 종결 JSON 한 줄로 인코딩(TCP 전송 단위). */
+export declare function encodeLine(value: unknown): string;
+/**
+ * TCP 청크를 누적해 완결된 라인(JSON)만 파싱해 내는 디코더를 만든다.
+ * 소켓은 메시지 경계를 보장하지 않으므로(청크 분할·병합) 개행으로 잘라
+ * 완성된 줄만 넘긴다. 파싱 불가한 줄은 건너뛴다.
+ */
+export declare function createLineDecoder<T>(): (chunk: string) => T[];
 /** JSON 을 NATS 페이로드(Uint8Array)로. */
 export declare function encodeJson(value: unknown): Uint8Array;
 /** NATS 페이로드(Uint8Array)를 JSON 으로. 실패 시 undefined. */

package/dist/protocol.js

@@ -1,10 +1,14 @@
-// @gaonjs/async · 실시간 와이어 프로토콜 (§7 · 질문 19 — 프로토콜은 구현 단계)
+// @gaonjs/async · 실시간 와이어 프로토콜 (§7 · errata E-2 2026-07-23)
 //
-// 세 경로의 메시지 형식을 한곳에 모은다:
+// 경로별 메시지 형식을 한곳에 모은다:
 //  1) 클라이언트 ↔ 웹서버 (WebSocket JSON 프레임)
-//  2) 웹서버 → 허브 (프레즌스 등록/해제/하트비트 · NATS)
-//  3) 허브 → 전 웹서버 (프레즌스 델타 브로드캐스트 · NATS)
-// 그리고 채널 브로드캐스트(웹서버 ↔ 웹서버, NATS)까지.
+//  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 상수 ──────────────────────────────────────────────────
 /** 웹서버 → 허브 프레즌스 명령(허브가 큐 구독). */
@@ -13,6 +17,40 @@ 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));

package/dist/runtime.d.ts

@@ -12,6 +12,9 @@ export interface ChannelRuntimeOptions {
     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> {

package/dist/runtime.js

@@ -11,7 +11,12 @@ import { createPresenceClient } from './presence.js';
 export async function createChannelRuntime(opts) {
     const nats = opts.nats;
     const presence = opts.presence ??
-        (await createPresenceClient({ nats, server: opts.server, heartbeatMs: opts.heartbeatMs }));
+        (await createPresenceClient({
+            nats,
+            server: opts.server,
+            hubAddr: opts.hubAddr,
+            heartbeatMs: opts.heartbeatMs,
+        }));
     const ownPresence = !opts.presence;
     const channels = new Map();
     const sendFrame = (socket, frame) => {

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