@interactive-inc/flume 0.9.4 → 0.10.0

package/dist/discord.d.ts

@@ -1,4 +1,4 @@
-import { r as FlumeDiscordSourceOptions, t as FlumeSource, w as FlumeSourceStartContext } from "./flume-source.js";
+import { D as FlumeSourceStartContext, o as FlumeDiscordSourceOptions, t as FlumeSource } from "./flume-source.js";
 
 //#region lib/discord/discord-source.d.ts
 declare class FlumeDiscordSource extends FlumeSource {

package/dist/discord.js

@@ -1,7 +1,7 @@
 import { a as FlumeStartError, c as safeNormalizeError, i as safeNow, l as safeErrorMessage, n as safeInvokeCallback, o as FlumeParseError, r as FlumeLogger, s as attempt, t as FlumeSource } from "./flume-source.js";
 import { t as FlumeConnectionError } from "./connection-error.js";
-import { i as safeRandom, n as scheduleFlumeReconnect, r as FlumeReconnector, t as safeStringify } from "./safe-stringify.js";
 import { t as isRecord } from "./is-record.js";
+import { i as safeRandom, n as scheduleFlumeReconnect, r as FlumeReconnector, t as safeStringify } from "./safe-stringify.js";
 import { t as safeJsonParse } from "./safe-json-parse.js";
 import { z } from "zod/v4";
 //#region lib/discord/discord-gateway-session.ts

package/dist/flume-source.d.ts

@@ -113,6 +113,15 @@ type FlumeStreamItem = {
   log: FlumeLog;
 };
 type FlumeStreamHandler = (item: FlumeStreamItem) => void;
+/**
+ * `FlumeConfluence` が onEvent に渡す item。Flume 単体の `FlumeStreamItem` に
+ * `groupId` (`add(id, ...)` で渡したグループ識別子) をスタンプしたもの。
+ * 合流ストリームの provenance を呼び出し側で復元する必要がなくなる
+ */
+type FlumeConfluenceItem = FlumeStreamItem & {
+  readonly groupId: string;
+};
+type FlumeConfluenceItemHandler = (item: FlumeConfluenceItem) => void;
 type FlumeStreamOverflow = "drop-oldest" | "drop-newest";
 type FlumeStreamOptions = {
   /** バッファ上限 (既定 1000)。consumer が遅れて溢れたら onOverflow に従う */buffer?: number; /** バッファ溢れ時の方針 (既定 "drop-oldest") */
@@ -207,9 +216,43 @@ type FlumeTimeMessage = {
   data?: Record<string, unknown>;
   meta?: Record<string, string>;
 };
+/**
+ * 起動 / 終了をまたいだ状態を 1 つ載せる純粋な DI ポート。flume 内部で fs / db / network を
+ * 触らないように、I/O の場所と方式は host が決める。load の失敗は null 復帰扱い、save の
+ * 失敗は best-effort (source 側で log するが throw しない)
+ */
+type FlumeStatePersister<S> = {
+  load(): Promise<S | null>;
+  save(state: S): Promise<void>;
+};
+/** `FlumeTimeSource` の statePersister が保存する形 */
+type FlumeTimeSourceState = {
+  readonly lastFiredAt: number;
+};
+/**
+ * `FlumeTimeSource` の起動時 catch-up 方針。statePersister が読めた lastFiredAt から
+ * 現在時刻までに過ぎ去った cron マッチを再発火するかどうかを決める。
+ *  - "off"      : 何もしない (既定。後方互換)
+ *  - "lastOnly" : 直近に過ぎ去ったマッチを 1 件だけ再発火
+ *  - "missed"   : maxWindowMs (既定 24h) 以内のすべての過ぎ去ったマッチを順に再発火
+ */
+type FlumeCatchupPolicy = {
+  readonly mode: "off";
+} | {
+  readonly mode: "lastOnly";
+} | {
+  readonly mode: "missed";
+  readonly maxWindowMs?: number;
+};
 type FlumeTimeSourceOptions = {
   /** 5 フィールド cron 式 (minute hour day-of-month month day-of-week)。壁時計 (local time) 基準 */cron: string;
   message?: (tick: FlumeTimeTick) => FlumeTimeMessage;
+  /**
+   * 起動 / 終了をまたいで `lastFiredAt` を覚えておく口。未指定なら catchup は無効化される
+   * (lastFiredAt が分からないので)。flume は fs / db を触らないので host が実装を渡す
+   */
+  statePersister?: FlumeStatePersister<FlumeTimeSourceState>; /** statePersister が読めた lastFiredAt を元に過去 tick を再発火する方針 (既定 "off") */
+  catchupPolicy?: FlumeCatchupPolicy;
 };
 type FlumeGatewayMessage = z.infer<typeof FlumeGatewayMessageSchema>;
 type FlumeSlackEnvelope = z.infer<typeof FlumeSlackEnvelopeSchema>;
@@ -272,4 +315,4 @@ declare abstract class FlumeSource {
   protected abstract disconnect(): Promise<void> | void;
 }
 //#endregion
-export { FlumeStreamOverflow as A, FlumeSourceName as C, FlumeStreamHandler as D, FlumeStatus as E, FlumeTimerHandle as F, FlumeLogger as I, FlumeTimeMessage as M, FlumeTimeSourceOptions as N, FlumeStreamItem as O, FlumeTimeTick as P, FlumeSourceLocalStatusHandler as S, FlumeSourceStatus as T, FlumeRuntimeDeps as _, FlumeEvent as a, FlumeSlackEvent as b, FlumeGitHubEvent as c, FlumeLog as d, FlumeLogHandler as f, FlumeReconnectOptions as g, FlumeReconnectConfig as h, FlumeErrorHandler as i, FlumeTimeEvent as j, FlumeStreamOptions as k, FlumeGitHubNotification as l, FlumeLogLevel as m, FlumeDiscordEvent as n, FlumeEventHandler as o, FlumeLogInput as p, FlumeDiscordSourceOptions as r, FlumeGatewayMessage as s, FlumeSource as t, FlumeGitHubSourceOptions as u, FlumeSlackConnectionResponse as v, FlumeSourceStartContext as w, FlumeSlackSourceOptions as x, FlumeSlackEnvelope as y };
+export { FlumeStatus as A, FlumeTimerHandle as B, FlumeSlackEvent as C, FlumeSourceStartContext as D, FlumeSourceName as E, FlumeTimeEvent as F, FlumeTimeMessage as I, FlumeTimeSourceOptions as L, FlumeStreamItem as M, FlumeStreamOptions as N, FlumeSourceStatus as O, FlumeStreamOverflow as P, FlumeTimeSourceState as R, FlumeSlackEnvelope as S, FlumeSourceLocalStatusHandler as T, FlumeLogger as V, FlumeLogLevel as _, FlumeDiscordEvent as a, FlumeRuntimeDeps as b, FlumeEvent as c, FlumeGitHubEvent as d, FlumeGitHubNotification as f, FlumeLogInput as g, FlumeLogHandler as h, FlumeConfluenceItemHandler as i, FlumeStreamHandler as j, FlumeStatePersister as k, FlumeEventHandler as l, FlumeLog as m, FlumeCatchupPolicy as n, FlumeDiscordSourceOptions as o, FlumeGitHubSourceOptions as p, FlumeConfluenceItem as r, FlumeErrorHandler as s, FlumeSource as t, FlumeGatewayMessage as u, FlumeReconnectConfig as v, FlumeSlackSourceOptions as w, FlumeSlackConnectionResponse as x, FlumeReconnectOptions as y, FlumeTimeTick as z };

package/dist/github.d.ts

@@ -1,4 +1,4 @@
-import { l as FlumeGitHubNotification, t as FlumeSource, u as FlumeGitHubSourceOptions, w as FlumeSourceStartContext } from "./flume-source.js";
+import { D as FlumeSourceStartContext, f as FlumeGitHubNotification, p as FlumeGitHubSourceOptions, t as FlumeSource } from "./flume-source.js";
 
 //#region lib/github/github-source.d.ts
 declare class FlumeGitHubSource extends FlumeSource {

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { A as FlumeStreamOverflow, C as FlumeSourceName, D as FlumeStreamHandler, E as FlumeStatus, F as FlumeTimerHandle, I as FlumeLogger, M as FlumeTimeMessage, N as FlumeTimeSourceOptions, O as FlumeStreamItem, P as FlumeTimeTick, S as FlumeSourceLocalStatusHandler, T as FlumeSourceStatus, _ as FlumeRuntimeDeps, a as FlumeEvent, b as FlumeSlackEvent, c as FlumeGitHubEvent, d as FlumeLog, f as FlumeLogHandler, g as FlumeReconnectOptions, h as FlumeReconnectConfig, i as FlumeErrorHandler, j as FlumeTimeEvent, k as FlumeStreamOptions, l as FlumeGitHubNotification, m as FlumeLogLevel, n as FlumeDiscordEvent, o as FlumeEventHandler, p as FlumeLogInput, r as FlumeDiscordSourceOptions, s as FlumeGatewayMessage, t as FlumeSource, u as FlumeGitHubSourceOptions, v as FlumeSlackConnectionResponse, w as FlumeSourceStartContext, x as FlumeSlackSourceOptions, y as FlumeSlackEnvelope } from "./flume-source.js";
-import { t as FlumeParseError } from "./parse-error.js";
+import { A as FlumeStatus, B as FlumeTimerHandle, C as FlumeSlackEvent, D as FlumeSourceStartContext, E as FlumeSourceName, F as FlumeTimeEvent, I as FlumeTimeMessage, L as FlumeTimeSourceOptions, M as FlumeStreamItem, N as FlumeStreamOptions, O as FlumeSourceStatus, P as FlumeStreamOverflow, R as FlumeTimeSourceState, S as FlumeSlackEnvelope, T as FlumeSourceLocalStatusHandler, V as FlumeLogger, _ as FlumeLogLevel, a as FlumeDiscordEvent, b as FlumeRuntimeDeps, c as FlumeEvent, d as FlumeGitHubEvent, f as FlumeGitHubNotification, g as FlumeLogInput, h as FlumeLogHandler, i as FlumeConfluenceItemHandler, j as FlumeStreamHandler, k as FlumeStatePersister, l as FlumeEventHandler, m as FlumeLog, n as FlumeCatchupPolicy, o as FlumeDiscordSourceOptions, p as FlumeGitHubSourceOptions, r as FlumeConfluenceItem, s as FlumeErrorHandler, t as FlumeSource, u as FlumeGatewayMessage, v as FlumeReconnectConfig, w as FlumeSlackSourceOptions, x as FlumeSlackConnectionResponse, y as FlumeReconnectOptions, z as FlumeTimeTick } from "./flume-source.js";
+import { i as FlumeParseError, r as FlumeTimeSource, t as FlumeCron } from "./parse-cron.js";
 
 //#region lib/deps.d.ts
 /**
@@ -29,14 +29,14 @@ declare class FlumeConnectionError extends Error {
 }
 //#endregion
 //#region lib/errors/http-error.d.ts
-type Props$4 = {
+type Props$5 = {
   message: string;
   status: number;
   cause?: unknown;
 };
 declare class FlumeHttpError extends Error {
   readonly status: number;
-  constructor(props: Props$4);
+  constructor(props: Props$5);
 }
 //#endregion
 //#region lib/errors/start-error.d.ts
@@ -48,7 +48,7 @@ declare class FlumeStartError extends Error {
 }
 //#endregion
 //#region lib/flume-stream.d.ts
-type Props$3 = {
+type Props$4 = {
   buffer: number;
   onOverflow: FlumeStreamOverflow;
   onClose: () => void;
@@ -63,7 +63,7 @@ declare class FlumeStream implements AsyncIterableIterator<FlumeStreamItem> {
   private readonly items;
   private readonly resolvers;
   private closed;
-  constructor(props: Props$3);
+  constructor(props: Props$4);
   push(item: FlumeStreamItem): void;
   close(): void;
   next(): Promise<IteratorResult<FlumeStreamItem>>;
@@ -89,7 +89,7 @@ type FlumeCloseError = {
   source: string;
   error: Error;
 };
-type Props$2 = {
+type Props$3 = {
   finalStatuses: ReadonlyArray<FlumeSourceStatus>;
   closeErrors: ReadonlyArray<FlumeCloseError>;
 };
@@ -101,7 +101,7 @@ type Props$2 = {
 declare class FlumeClosed {
   private readonly props;
   readonly kind: "closed";
-  constructor(props: Props$2);
+  constructor(props: Props$3);
   statuses(): ReadonlyArray<FlumeSourceStatus>;
   /**
    * `runClose` 中に `source.stop()` が rejected で settle した source の名前と
@@ -112,7 +112,7 @@ declare class FlumeClosed {
 }
 //#endregion
 //#region lib/flume-running.d.ts
-type Props$1 = {
+type Props$2 = {
   sources: ReadonlyArray<FlumeSource>;
   signal?: AbortSignal;
   log: FlumeLogger;
@@ -128,7 +128,7 @@ declare class FlumeRunning {
   readonly kind: "running";
   private closePromise;
   private readonly onAbort;
-  constructor(props: Props$1);
+  constructor(props: Props$2);
   close(): Promise<FlumeClosed>;
   statuses(): ReadonlyArray<FlumeSourceStatus>;
   /**
@@ -198,8 +198,12 @@ declare class Flume {
 }
 //#endregion
 //#region lib/flume-confluence.d.ts
-type Props = {
-  /** 配下の全 Flume の firehose をここへ合流させる単一 sink */onEvent?: FlumeStreamHandler; /** error レベル log だけ (全 Flume 共通) */
+type Props$1 = {
+  /**
+   * 配下の全 Flume の firehose をここへ合流させる単一 sink。
+   * 各 item には発信元グループの id が `groupId` としてスタンプされる
+   */
+  onEvent?: FlumeConfluenceItemHandler; /** error レベル log だけ (全 Flume 共通) */
   onError?: FlumeErrorHandler;
   deps?: FlumeRuntimeDeps;
   reconnect?: FlumeReconnectOptions;
@@ -207,22 +211,62 @@ type Props = {
 /**
  * 複数の `Flume` を束ねて動的に増減させる上位レイヤー。各 Flume は immutable のまま、
  * `add()` で新しいグループを起動し `remove()` で個別に停止する。全グループの firehose は
- * `onEvent` 1 本に合流する。Flume 本体の FSM / rollback / reconnect はそのまま再利用される。
+ * `onEvent` 1 本に合流し、各 item には発信元グループ id が `groupId` としてスタンプされる。
+ * Flume 本体の FSM / rollback / reconnect はそのまま再利用される。
  *
- * id はグループの管理ハンドル (add/remove 用)。合流ストリーム自体は id を持たず、
- * item の中の source 名で発信元を判別する。throw しない流儀に従い `add()` は `Error | null` を返す
+ * `replace(id, sources)` は同じ id のグループを差し替える。新グループを先に起動し、
+ * 起動成功時にのみ旧グループを停止するので連続稼働を維持できる (token rotation 用途)。
+ * 起動失敗時は旧グループはそのまま走り続ける。
+ *
+ * throw しない流儀に従い `add()` / `replace()` は `Error | null` を返す
  */
 declare class FlumeConfluence {
   private readonly props;
   private readonly running;
-  constructor(props?: Props);
+  private readonly deps;
+  constructor(props?: Props$1);
   /** sources を 1 グループとして起動。id 重複や起動失敗は `Error` で返す (throw しない) */
   add(id: string, sources: ReadonlyArray<FlumeSource>): Promise<Error | null>;
+  /**
+   * 既存グループを新しい sources で差し替える。新グループを先に起動し、成功時のみ旧を停止する。
+   * 起動失敗 / replaceTimeoutMs (既定 10s) 経過時は新グループを破棄し旧を走らせたまま返す。
+   * 旧グループが存在しない場合は `Error` を返す (replace は add と違ってグループの存在を前提とする)
+   */
+  replace(id: string, sources: ReadonlyArray<FlumeSource>, options?: {
+    readonly replaceTimeoutMs?: number;
+  }): Promise<Error | null>;
   /** 指定グループだけ close。他グループは無停止。未知の id は no-op */
   remove(id: string): Promise<void>;
   closeAll(): Promise<void>;
   has(id: string): boolean;
   ids(): ReadonlyArray<string>;
+  /**
+   * 1 グループ分の Flume を開いて FlumeRunning を返す。timeoutMs を指定すると open() を
+   * AbortSignal でレース掛けし、超過時に新グループ起動を中止する。失敗時の rollback は
+   * Flume 本体に任せる
+   */
+  private openGroup;
+  private wrapOnEvent;
 }
 //#endregion
-export { Flume, type FlumeCloseError, FlumeClosed, FlumeConfluence, FlumeConnectionError, type FlumeDiscordEvent, type FlumeDiscordSourceOptions, type FlumeErrorHandler, type FlumeEvent, type FlumeEventHandler, type FlumeGatewayMessage, type FlumeGitHubEvent, type FlumeGitHubNotification, type FlumeGitHubSourceOptions, FlumeHttpError, type FlumeLog, type FlumeLogHandler, type FlumeLogInput, type FlumeLogLevel, type FlumeOptions, FlumeParseError, type FlumeReconnectConfig, type FlumeReconnectOptions, FlumeRunning, type FlumeRuntimeDeps, type FlumeSlackConnectionResponse, type FlumeSlackEnvelope, type FlumeSlackEvent, type FlumeSlackSourceOptions, FlumeSource, type FlumeSourceLocalStatusHandler, type FlumeSourceName, type FlumeSourceStartContext, type FlumeSourceStatus, FlumeStartError, type FlumeStatus, type FlumeStreamHandler, type FlumeStreamItem, type FlumeStreamOptions, type FlumeStreamOverflow, type FlumeTimeEvent, type FlumeTimeMessage, type FlumeTimeSourceOptions, type FlumeTimeTick, type FlumeTimerHandle, createFlumeDefaultDeps };
+//#region lib/time/time-catchup.d.ts
+type Props = {
+  cron: FlumeCron;
+  lastFiredAt: number;
+  now: number;
+  policy: FlumeCatchupPolicy;
+};
+/**
+ * `lastFiredAt` から `now` までに過ぎ去った cron マッチを policy に従って列挙する。
+ *
+ * - policy.mode === "off"      : 常に空配列
+ * - policy.mode === "lastOnly" : 過ぎ去ったマッチの中で最も新しいもの 1 件
+ * - policy.mode === "missed"   : maxWindowMs (既定 24h) 以内に過ぎ去ったすべてのマッチ。
+ *                                window の起点は `max(lastFiredAt, now - maxWindowMs)`
+ *
+ * 到達不能 cron や catastrophic な policy ミス指定の場合は FlumeParseError を返す
+ * (catchup 列挙だけで失敗させる。source 本体の起動は別判断)
+ */
+declare function flumeCollectCatchupMatches(props: Props): ReadonlyArray<number> | FlumeParseError;
+//#endregion
+export { Flume, type FlumeCatchupPolicy, type FlumeCloseError, FlumeClosed, FlumeConfluence, type FlumeConfluenceItem, type FlumeConfluenceItemHandler, FlumeConnectionError, type FlumeDiscordEvent, type FlumeDiscordSourceOptions, type FlumeErrorHandler, type FlumeEvent, type FlumeEventHandler, type FlumeGatewayMessage, type FlumeGitHubEvent, type FlumeGitHubNotification, type FlumeGitHubSourceOptions, FlumeHttpError, type FlumeLog, type FlumeLogHandler, type FlumeLogInput, type FlumeLogLevel, type FlumeOptions, FlumeParseError, type FlumeReconnectConfig, type FlumeReconnectOptions, FlumeRunning, type FlumeRuntimeDeps, type FlumeSlackConnectionResponse, type FlumeSlackEnvelope, type FlumeSlackEvent, type FlumeSlackSourceOptions, FlumeSource, type FlumeSourceLocalStatusHandler, type FlumeSourceName, type FlumeSourceStartContext, type FlumeSourceStatus, FlumeStartError, type FlumeStatePersister, type FlumeStatus, type FlumeStreamHandler, type FlumeStreamItem, type FlumeStreamOptions, type FlumeStreamOverflow, type FlumeTimeEvent, type FlumeTimeMessage, FlumeTimeSource, type FlumeTimeSourceOptions, type FlumeTimeSourceState, type FlumeTimeTick, type FlumeTimerHandle, createFlumeDefaultDeps, flumeCollectCatchupMatches };

package/dist/index.js

@@ -1,6 +1,7 @@
 import { a as FlumeStartError, c as safeNormalizeError, l as safeErrorMessage, n as safeInvokeCallback, o as FlumeParseError, r as FlumeLogger, s as attempt, t as FlumeSource } from "./flume-source.js";
 import { t as FlumeConnectionError } from "./connection-error.js";
 import { t as FlumeHttpError } from "./http-error.js";
+import { n as flumeCollectCatchupMatches, t as FlumeTimeSource } from "./time-source.js";
 //#region lib/deps.ts
 /**
 * `globalThis.WebSocket` の現在の値を返す。
@@ -520,30 +521,31 @@ var Flume = class {
 };
 //#endregion
 //#region lib/flume-confluence.ts
+const DEFAULT_REPLACE_TIMEOUT_MS = 1e4;
 /**
 * 複数の `Flume` を束ねて動的に増減させる上位レイヤー。各 Flume は immutable のまま、
 * `add()` で新しいグループを起動し `remove()` で個別に停止する。全グループの firehose は
-* `onEvent` 1 本に合流する。Flume 本体の FSM / rollback / reconnect はそのまま再利用される。
+* `onEvent` 1 本に合流し、各 item には発信元グループ id が `groupId` としてスタンプされる。
+* Flume 本体の FSM / rollback / reconnect はそのまま再利用される。
 *
-* id はグループの管理ハンドル (add/remove 用)。合流ストリーム自体は id を持たず、
-* item の中の source 名で発信元を判別する。throw しない流儀に従い `add()` は `Error | null` を返す
+* `replace(id, sources)` は同じ id のグループを差し替える。新グループを先に起動し、
+* 起動成功時にのみ旧グループを停止するので連続稼働を維持できる (token rotation 用途)。
+* 起動失敗時は旧グループはそのまま走り続ける。
+*
+* throw しない流儀に従い `add()` / `replace()` は `Error | null` を返す
 */
 var FlumeConfluence = class {
 	props;
 	running = /* @__PURE__ */ new Map();
+	deps;
 	constructor(props = {}) {
 		this.props = props;
+		this.deps = props.deps ?? createFlumeDefaultDeps();
 	}
 	/** sources を 1 グループとして起動。id 重複や起動失敗は `Error` で返す (throw しない) */
 	async add(id, sources) {
 		if (this.running.has(id)) return new FlumeStartError(`FlumeConfluence: id already added: ${id}`);
-		const running = await new Flume({
-			sources,
-			onEvent: this.props.onEvent,
-			onError: this.props.onError,
-			deps: this.props.deps,
-			reconnect: this.props.reconnect
-		}).open();
+		const running = await this.openGroup(id, sources, void 0);
 		if (running instanceof Error) return running;
 		if (this.running.has(id)) {
 			await running.close();
@@ -552,6 +554,25 @@ var FlumeConfluence = class {
 		this.running.set(id, running);
 		return null;
 	}
+	/**
+	* 既存グループを新しい sources で差し替える。新グループを先に起動し、成功時のみ旧を停止する。
+	* 起動失敗 / replaceTimeoutMs (既定 10s) 経過時は新グループを破棄し旧を走らせたまま返す。
+	* 旧グループが存在しない場合は `Error` を返す (replace は add と違ってグループの存在を前提とする)
+	*/
+	async replace(id, sources, options) {
+		const previous = this.running.get(id);
+		if (!previous) return new FlumeStartError(`FlumeConfluence: id not running: ${id}`);
+		const timeoutMs = options?.replaceTimeoutMs ?? DEFAULT_REPLACE_TIMEOUT_MS;
+		const next = await this.openGroup(id, sources, timeoutMs);
+		if (next instanceof Error) return next;
+		if (this.running.get(id) !== previous) {
+			await next.close();
+			return new FlumeStartError(`FlumeConfluence: ${id} concurrently mutated during replace`);
+		}
+		this.running.set(id, next);
+		await previous.close();
+		return null;
+	}
 	/** 指定グループだけ close。他グループは無停止。未知の id は no-op */
 	async remove(id) {
 		const running = this.running.get(id);
@@ -569,6 +590,39 @@ var FlumeConfluence = class {
 	ids() {
 		return [...this.running.keys()];
 	}
+	/**
+	* 1 グループ分の Flume を開いて FlumeRunning を返す。timeoutMs を指定すると open() を
+	* AbortSignal でレース掛けし、超過時に新グループ起動を中止する。失敗時の rollback は
+	* Flume 本体に任せる
+	*/
+	async openGroup(id, sources, timeoutMs) {
+		const controller = timeoutMs === void 0 ? null : new AbortController();
+		const timeoutHandle = controller === null ? null : this.deps.setTimeout(() => controller.abort(), timeoutMs ?? DEFAULT_REPLACE_TIMEOUT_MS);
+		const result = await new Flume({
+			sources,
+			onEvent: this.wrapOnEvent(id),
+			onError: this.props.onError,
+			deps: this.props.deps,
+			reconnect: this.props.reconnect,
+			signal: controller?.signal
+		}).open();
+		if (timeoutHandle !== null) this.deps.clearTimeout(timeoutHandle);
+		if (result instanceof Error) {
+			if (controller !== null && controller.signal.aborted) return new FlumeStartError(`FlumeConfluence: open of "${id}" timed out after ${timeoutMs}ms`);
+			return result;
+		}
+		return result;
+	}
+	wrapOnEvent(id) {
+		const onEvent = this.props.onEvent;
+		if (!onEvent) return void 0;
+		return (item) => {
+			onEvent({
+				...item,
+				groupId: id
+			});
+		};
+	}
 };
 //#endregion
-export { Flume, FlumeClosed, FlumeConfluence, FlumeConnectionError, FlumeHttpError, FlumeParseError, FlumeRunning, FlumeSource, FlumeStartError, createFlumeDefaultDeps };
+export { Flume, FlumeClosed, FlumeConfluence, FlumeConnectionError, FlumeHttpError, FlumeParseError, FlumeRunning, FlumeSource, FlumeStartError, FlumeTimeSource, createFlumeDefaultDeps, flumeCollectCatchupMatches };

package/dist/parse-cron.d.ts

@@ -0,0 +1,55 @@
+import { D as FlumeSourceStartContext, L as FlumeTimeSourceOptions, t as FlumeSource } from "./flume-source.js";
+
+//#region lib/errors/parse-error.d.ts
+type Options = {
+  cause?: unknown;
+};
+declare class FlumeParseError extends Error {
+  constructor(message: string, options?: Options);
+}
+//#endregion
+//#region lib/time/time-source.d.ts
+/**
+ * cron スケジュールで tick を emit する Source。外部接続を持たないため
+ * 起動成功と同時に `connected` になり reconnect の対象外。
+ *
+ * options.statePersister + options.catchupPolicy を渡すと:
+ *  1. 起動時に lastFiredAt を読み出す
+ *  2. lastFiredAt から now までの過ぎ去った cron マッチを policy に従って再発火する
+ *  3. 各 tick 後に lastFiredAt を保存する (best-effort, ブロックしない)
+ *
+ * 保存先や形式は flume の関知ではなく statePersister の実装が決める (純粋 DI)
+ */
+declare class FlumeTimeSource extends FlumeSource {
+  private readonly options;
+  readonly name: "time";
+  private scheduler;
+  constructor(options: FlumeTimeSourceOptions);
+  protected connect(ctx: FlumeSourceStartContext): Promise<Error | null>;
+  protected disconnect(): void;
+  private handleTick;
+  private emitTick;
+  private runCatchup;
+  private loadLastFiredAt;
+  private saveLastFiredAt;
+  private safeMessage;
+  private normalizeMeta;
+}
+//#endregion
+//#region lib/time/parse-cron.d.ts
+type FlumeCron = {
+  source: string;
+  minutes: ReadonlySet<number>;
+  hours: ReadonlySet<number>;
+  daysOfMonth: ReadonlySet<number>;
+  months: ReadonlySet<number>;
+  daysOfWeek: ReadonlySet<number>; /** day-of-month フィールドが `*` 以外か。dow と両方制限時は OR マッチ (標準 cron 準拠) */
+  domRestricted: boolean;
+  dowRestricted: boolean;
+};
+/**
+ * 5 フィールド cron 式をパースする。dow は 0-7 を許可し 7 を 0 (日曜) に正規化する
+ */
+declare function parseCron(expression: string): FlumeCron | FlumeParseError;
+//#endregion
+export { FlumeParseError as i, parseCron as n, FlumeTimeSource as r, FlumeCron as t };

package/dist/slack.d.ts

@@ -1,4 +1,4 @@
-import { t as FlumeSource, w as FlumeSourceStartContext, x as FlumeSlackSourceOptions, y as FlumeSlackEnvelope } from "./flume-source.js";
+import { D as FlumeSourceStartContext, S as FlumeSlackEnvelope, t as FlumeSource, w as FlumeSlackSourceOptions } from "./flume-source.js";
 
 //#region lib/slack/slack-source.d.ts
 declare class FlumeSlackSource extends FlumeSource {

package/dist/slack.js

@@ -1,8 +1,8 @@
 import { a as FlumeStartError, c as safeNormalizeError, i as safeNow, l as safeErrorMessage, o as FlumeParseError, r as FlumeLogger, s as attempt, t as FlumeSource } from "./flume-source.js";
 import { t as FlumeConnectionError } from "./connection-error.js";
 import { t as FlumeHttpError } from "./http-error.js";
-import { n as scheduleFlumeReconnect, r as FlumeReconnector, t as safeStringify } from "./safe-stringify.js";
 import { t as isRecord } from "./is-record.js";
+import { n as scheduleFlumeReconnect, r as FlumeReconnector, t as safeStringify } from "./safe-stringify.js";
 import { t as safeJsonParse } from "./safe-json-parse.js";
 import { t as safeReadText } from "./safe-read-text.js";
 import { z } from "zod/v4";

package/dist/time-source.js

@@ -0,0 +1,427 @@
+import { a as FlumeStartError, c as safeNormalizeError, i as safeNow, l as safeErrorMessage, n as safeInvokeCallback, o as FlumeParseError, r as FlumeLogger, s as attempt, t as FlumeSource } from "./flume-source.js";
+import { t as isRecord } from "./is-record.js";
+//#region lib/time/parse-cron-field.ts
+/**
+* 単一 cron フィールド (minute など) の spec を許可値の Set に展開する。
+* 対応: `*` / `* /n` / `a` / `a-b` / `a-b/n` とそれらのカンマ区切り。名前 (JAN, MON) は非対応
+*/
+function parseCronField(spec, min, max) {
+	const values = /* @__PURE__ */ new Set();
+	for (const part of spec.split(",")) {
+		const expanded = expandCronPart(part, min, max);
+		if (expanded instanceof FlumeParseError) return expanded;
+		for (const value of expanded) values.add(value);
+	}
+	if (values.size === 0) return new FlumeParseError(`cron field empty: "${spec}"`);
+	return values;
+}
+function expandCronPart(part, min, max) {
+	let range = part;
+	let step = 1;
+	const slash = part.indexOf("/");
+	if (slash !== -1) {
+		range = part.slice(0, slash);
+		const parsed = Number(part.slice(slash + 1));
+		if (!Number.isInteger(parsed) || parsed <= 0) return new FlumeParseError(`invalid cron step: "${part}"`);
+		step = parsed;
+	}
+	const bounds = resolveBounds(range, min, max);
+	if (bounds instanceof FlumeParseError) return bounds;
+	const numbers = [];
+	for (let value = bounds.lo; value <= bounds.hi; value += step) numbers.push(value);
+	return numbers;
+}
+function resolveBounds(range, min, max) {
+	if (range === "*") return {
+		lo: min,
+		hi: max
+	};
+	const dash = range.indexOf("-");
+	const lo = dash === -1 ? Number(range) : Number(range.slice(0, dash));
+	const hi = dash === -1 ? lo : Number(range.slice(dash + 1));
+	if (!Number.isInteger(lo) || !Number.isInteger(hi)) return new FlumeParseError(`invalid cron range: "${range}"`);
+	if (lo < min || hi > max || lo > hi) return new FlumeParseError(`cron value out of range [${min}-${max}]: "${range}"`);
+	return {
+		lo,
+		hi
+	};
+}
+//#endregion
+//#region lib/time/parse-cron.ts
+/**
+* 5 フィールド cron 式をパースする。dow は 0-7 を許可し 7 を 0 (日曜) に正規化する
+*/
+function parseCron(expression) {
+	const trimmed = expression.trim();
+	const fields = trimmed.split(/\s+/);
+	if (fields.length !== 5) return new FlumeParseError(`cron must have 5 fields, got ${fields.length}: "${expression}"`);
+	const minutes = parseCronField(fields[0] ?? "", 0, 59);
+	if (minutes instanceof FlumeParseError) return minutes;
+	const hours = parseCronField(fields[1] ?? "", 0, 23);
+	if (hours instanceof FlumeParseError) return hours;
+	const daysOfMonth = parseCronField(fields[2] ?? "", 1, 31);
+	if (daysOfMonth instanceof FlumeParseError) return daysOfMonth;
+	const months = parseCronField(fields[3] ?? "", 1, 12);
+	if (months instanceof FlumeParseError) return months;
+	const rawDaysOfWeek = parseCronField(fields[4] ?? "", 0, 7);
+	if (rawDaysOfWeek instanceof FlumeParseError) return rawDaysOfWeek;
+	const daysOfWeek = /* @__PURE__ */ new Set();
+	for (const value of rawDaysOfWeek) daysOfWeek.add(value === 7 ? 0 : value);
+	return {
+		source: trimmed,
+		minutes,
+		hours,
+		daysOfMonth,
+		months,
+		daysOfWeek,
+		domRestricted: fields[2] !== "*",
+		dowRestricted: fields[4] !== "*"
+	};
+}
+//#endregion
+//#region lib/time/cron-next.ts
+const MINUTE_MS = 6e4;
+const MAX_ITERATIONS = 5e5;
+/**
+* `afterMs` より後の最初の cron マッチ時刻 (epoch ms) を壁時計 (local time) で求める。
+* 到達不能なら FlumeParseError を返す
+*/
+function flumeCronNext(cron, afterMs) {
+	let candidate = Math.floor(afterMs / MINUTE_MS) * MINUTE_MS + MINUTE_MS;
+	for (let iteration = 0; iteration < MAX_ITERATIONS; iteration++) {
+		const date = new Date(candidate);
+		if (!cron.months.has(date.getMonth() + 1)) {
+			candidate = new Date(date.getFullYear(), date.getMonth() + 1, 1, 0, 0, 0, 0).getTime();
+			continue;
+		}
+		if (!matchesDay(cron, date)) {
+			candidate = new Date(date.getFullYear(), date.getMonth(), date.getDate() + 1, 0, 0, 0, 0).getTime();
+			continue;
+		}
+		if (!cron.hours.has(date.getHours())) {
+			candidate = new Date(date.getFullYear(), date.getMonth(), date.getDate(), date.getHours() + 1, 0, 0, 0).getTime();
+			continue;
+		}
+		if (!cron.minutes.has(date.getMinutes())) {
+			candidate += MINUTE_MS;
+			continue;
+		}
+		return candidate;
+	}
+	return new FlumeParseError(`cron "${cron.source}" has no next time within bound`);
+}
+function matchesDay(cron, date) {
+	const domMatch = cron.daysOfMonth.has(date.getDate());
+	const dowMatch = cron.daysOfWeek.has(date.getDay());
+	if (cron.domRestricted && cron.dowRestricted) return domMatch || dowMatch;
+	if (cron.domRestricted) return domMatch;
+	if (cron.dowRestricted) return dowMatch;
+	return true;
+}
+//#endregion
+//#region lib/time/time-scheduler.ts
+const MAX_TIMEOUT_MS = 2e9;
+const FIRE_TOLERANCE_MS = 1e3;
+/**
+* cron に従って `onTick` を駆動するタイマーループ。外部接続を持たないため reconnect 不要。
+* IO 境界は全て `attempt` 経由で扱い、停止後はコールバックを発火しない
+*/
+var FlumeTimeScheduler = class {
+	props;
+	log;
+	isStoppedFlag = false;
+	timer = null;
+	target = 0;
+	constructor(props) {
+		this.props = props;
+		this.log = new FlumeLogger({
+			source: "time.scheduler",
+			handler: props.onLog,
+			deps: props.deps
+		});
+	}
+	get isStopped() {
+		return this.isStoppedFlag;
+	}
+	start() {
+		const next = flumeCronNext(this.props.cron, safeNow({ deps: this.props.deps }));
+		if (next instanceof FlumeParseError) {
+			this.log.error({
+				action: "cron.no-next",
+				message: next.message,
+				error: next
+			});
+			return next;
+		}
+		this.target = next;
+		this.log.info({
+			action: "scheduler.start",
+			message: `next fire at ${new Date(next).toISOString()}`,
+			detail: { target: next }
+		});
+		this.arm();
+		return null;
+	}
+	stop() {
+		this.isStoppedFlag = true;
+		this.clearTimer();
+	}
+	arm() {
+		this.clearTimer();
+		const delay = Math.max(0, this.target - safeNow({ deps: this.props.deps }));
+		const capped = Math.min(delay, MAX_TIMEOUT_MS);
+		const result = attempt(() => this.props.deps.setTimeout(() => this.onWake(), capped));
+		if (result instanceof Error) {
+			this.log.error({
+				action: "scheduler.arm.error",
+				message: safeErrorMessage({ error: result }),
+				error: result
+			});
+			this.timer = null;
+			return;
+		}
+		this.timer = result;
+	}
+	onWake() {
+		this.timer = null;
+		if (this.isStoppedFlag) return;
+		if (this.target - safeNow({ deps: this.props.deps }) > FIRE_TOLERANCE_MS) {
+			this.arm();
+			return;
+		}
+		const firedAt = this.target;
+		safeInvokeCallback({
+			fn: () => this.props.onTick(firedAt),
+			onError: (error) => {
+				this.log.error({
+					action: "scheduler.tick.error",
+					message: safeErrorMessage({ error }),
+					error
+				});
+			}
+		});
+		const next = flumeCronNext(this.props.cron, firedAt);
+		if (next instanceof FlumeParseError) {
+			this.log.error({
+				action: "cron.no-next",
+				message: next.message,
+				error: next
+			});
+			return;
+		}
+		this.target = next;
+		this.arm();
+	}
+	clearTimer() {
+		if (this.timer === null) return;
+		const handle = this.timer;
+		const result = attempt(() => this.props.deps.clearTimeout(handle));
+		if (result instanceof Error) this.log.error({
+			action: "scheduler.timer.clear.error",
+			message: safeErrorMessage({ error: result }),
+			error: result
+		});
+		this.timer = null;
+	}
+};
+//#endregion
+//#region lib/time/time-catchup.ts
+const DEFAULT_MISSED_WINDOW_MS = 1440 * 60 * 1e3;
+const MAX_CATCHUP_MATCHES = 1e4;
+/**
+* `lastFiredAt` から `now` までに過ぎ去った cron マッチを policy に従って列挙する。
+*
+* - policy.mode === "off"      : 常に空配列
+* - policy.mode === "lastOnly" : 過ぎ去ったマッチの中で最も新しいもの 1 件
+* - policy.mode === "missed"   : maxWindowMs (既定 24h) 以内に過ぎ去ったすべてのマッチ。
+*                                window の起点は `max(lastFiredAt, now - maxWindowMs)`
+*
+* 到達不能 cron や catastrophic な policy ミス指定の場合は FlumeParseError を返す
+* (catchup 列挙だけで失敗させる。source 本体の起動は別判断)
+*/
+function flumeCollectCatchupMatches(props) {
+	if (props.policy.mode === "off") return [];
+	if (props.lastFiredAt >= props.now) return [];
+	const windowStart = props.policy.mode === "missed" ? Math.max(props.lastFiredAt, props.now - (props.policy.maxWindowMs ?? DEFAULT_MISSED_WINDOW_MS)) : props.lastFiredAt;
+	const matches = [];
+	let cursor = windowStart;
+	for (let i = 0; i < MAX_CATCHUP_MATCHES; i++) {
+		const next = flumeCronNext(props.cron, cursor);
+		if (next instanceof FlumeParseError) return next;
+		if (next > props.now) break;
+		matches.push(next);
+		cursor = next;
+	}
+	if (props.policy.mode === "lastOnly") {
+		const last = matches[matches.length - 1];
+		return last === void 0 ? [] : [last];
+	}
+	return matches;
+}
+//#endregion
+//#region lib/time/time-source.ts
+/**
+* cron スケジュールで tick を emit する Source。外部接続を持たないため
+* 起動成功と同時に `connected` になり reconnect の対象外。
+*
+* options.statePersister + options.catchupPolicy を渡すと:
+*  1. 起動時に lastFiredAt を読み出す
+*  2. lastFiredAt から now までの過ぎ去った cron マッチを policy に従って再発火する
+*  3. 各 tick 後に lastFiredAt を保存する (best-effort, ブロックしない)
+*
+* 保存先や形式は flume の関知ではなく statePersister の実装が決める (純粋 DI)
+*/
+var FlumeTimeSource = class extends FlumeSource {
+	options;
+	name = "time";
+	scheduler = null;
+	constructor(options) {
+		super();
+		this.options = options;
+	}
+	async connect(ctx) {
+		this.setStatus("connecting");
+		const cron = parseCron(this.options.cron);
+		if (cron instanceof FlumeParseError) {
+			const error = new FlumeStartError(`Time source: invalid cron "${this.options.cron}": ${cron.message}`);
+			ctx.log.error({
+				action: "source.start.failed",
+				message: safeErrorMessage({ error }),
+				error
+			});
+			this.setStatus("disconnected", error.message);
+			return error;
+		}
+		const persister = this.options.statePersister ?? null;
+		const lastFiredAt = persister === null ? null : await this.loadLastFiredAt(ctx, persister);
+		this.scheduler = new FlumeTimeScheduler({
+			cron,
+			onLog: ctx.log.handler,
+			deps: ctx.deps,
+			onTick: (firedAt) => this.handleTick(ctx, firedAt, persister)
+		});
+		const result = this.scheduler.start();
+		if (result instanceof Error) {
+			const error = new FlumeStartError(`Time source: ${safeErrorMessage({ error: result })}`);
+			this.setStatus("disconnected", error.message);
+			return error;
+		}
+		this.setStatus("connected");
+		if (lastFiredAt !== null && persister !== null) this.runCatchup({
+			ctx,
+			cron,
+			lastFiredAt,
+			persister
+		});
+		return null;
+	}
+	disconnect() {
+		this.scheduler?.stop();
+		this.scheduler = null;
+	}
+	handleTick(ctx, firedAt, persister) {
+		this.emitTick(ctx, firedAt);
+		if (persister !== null) this.saveLastFiredAt(ctx, persister, firedAt);
+	}
+	emitTick(ctx, firedAt) {
+		const tick = {
+			firedAt,
+			cron: this.options.cron
+		};
+		const custom = this.safeMessage(ctx, tick);
+		this.emit({
+			source: "time",
+			type: typeof custom.type === "string" ? custom.type : "tick",
+			data: isRecord(custom.data) ? custom.data : {
+				firedAt,
+				cron: this.options.cron
+			},
+			meta: this.normalizeMeta(custom.meta, this.options.cron),
+			receivedAt: safeNow({ deps: ctx.deps })
+		});
+	}
+	runCatchup(props) {
+		const policy = this.options.catchupPolicy ?? { mode: "off" };
+		if (policy.mode === "off") return;
+		const matches = flumeCollectCatchupMatches({
+			cron: props.cron,
+			lastFiredAt: props.lastFiredAt,
+			now: safeNow({ deps: props.ctx.deps }),
+			policy
+		});
+		if (matches instanceof FlumeParseError) {
+			props.ctx.log.warn({
+				action: "time.catchup.failed",
+				message: matches.message,
+				error: matches
+			});
+			return;
+		}
+		if (matches.length === 0) return;
+		props.ctx.log.info({
+			action: "time.catchup.fired",
+			message: `catchup ${matches.length} missed tick(s) since ${new Date(props.lastFiredAt).toISOString()}`,
+			detail: {
+				count: matches.length,
+				policy: policy.mode
+			}
+		});
+		for (const firedAt of matches) this.emitTick(props.ctx, firedAt);
+		const last = matches[matches.length - 1];
+		if (last !== void 0) this.saveLastFiredAt(props.ctx, props.persister, last);
+	}
+	async loadLastFiredAt(ctx, persister) {
+		const result = await attempt(() => persister.load());
+		if (result instanceof Error) {
+			ctx.log.warn({
+				action: "time.state.load.error",
+				message: safeErrorMessage({ error: result }),
+				error: result
+			});
+			return null;
+		}
+		if (result === null) return null;
+		if (typeof result.lastFiredAt !== "number" || !Number.isFinite(result.lastFiredAt)) return null;
+		return result.lastFiredAt;
+	}
+	saveLastFiredAt(ctx, persister, lastFiredAt) {
+		safeInvokeCallback({
+			fn: () => persister.save({ lastFiredAt }),
+			onError: (error) => {
+				ctx.log.warn({
+					action: "time.state.save.error",
+					message: safeErrorMessage({ error: safeNormalizeError({ value: error }) }),
+					error
+				});
+			}
+		});
+	}
+	safeMessage(ctx, tick) {
+		const message = this.options.message;
+		if (!message) return {};
+		const result = attempt(() => message(tick));
+		if (result instanceof Error) {
+			const error = safeNormalizeError({ value: result });
+			ctx.log.warn({
+				action: "message.error",
+				message: safeErrorMessage({ error }),
+				error,
+				detail: { firedAt: tick.firedAt }
+			});
+			return {};
+		}
+		return isRecord(result) ? result : {};
+	}
+	normalizeMeta(meta, cron) {
+		if (!isRecord(meta)) return { cron };
+		const normalized = {};
+		for (const key of Object.keys(meta)) {
+			const value = meta[key];
+			if (typeof value === "string") normalized[key] = value;
+		}
+		if (Object.keys(normalized).length === 0) return { cron };
+		return normalized;
+	}
+};
+//#endregion
+export { parseCron as i, flumeCollectCatchupMatches as n, flumeCronNext as r, FlumeTimeSource as t };

package/dist/time.d.ts

@@ -1,40 +1,5 @@
-import { N as FlumeTimeSourceOptions, t as FlumeSource, w as FlumeSourceStartContext } from "./flume-source.js";
-import { t as FlumeParseError } from "./parse-error.js";
+import { i as FlumeParseError, n as parseCron, r as FlumeTimeSource, t as FlumeCron } from "./parse-cron.js";
 
-//#region lib/time/time-source.d.ts
-/**
- * cron スケジュールで tick を emit する Source。外部接続を持たないため
- * 起動成功と同時に `connected` になり reconnect の対象外。
- * `options.message` で tick ごとの type / data / meta を上書きできる
- */
-declare class FlumeTimeSource extends FlumeSource {
-  private readonly options;
-  readonly name: "time";
-  private scheduler;
-  constructor(options: FlumeTimeSourceOptions);
-  protected connect(ctx: FlumeSourceStartContext): Promise<Error | null>;
-  protected disconnect(): void;
-  private handleTick;
-  private safeMessage;
-  private normalizeMeta;
-}
-//#endregion
-//#region lib/time/parse-cron.d.ts
-type FlumeCron = {
-  source: string;
-  minutes: ReadonlySet<number>;
-  hours: ReadonlySet<number>;
-  daysOfMonth: ReadonlySet<number>;
-  months: ReadonlySet<number>;
-  daysOfWeek: ReadonlySet<number>; /** day-of-month フィールドが `*` 以外か。dow と両方制限時は OR マッチ (標準 cron 準拠) */
-  domRestricted: boolean;
-  dowRestricted: boolean;
-};
-/**
- * 5 フィールド cron 式をパースする。dow は 0-7 を許可し 7 を 0 (日曜) に正規化する
- */
-declare function parseCron(expression: string): FlumeCron | FlumeParseError;
-//#endregion
 //#region lib/time/cron-next.d.ts
 /**
  * `afterMs` より後の最初の cron マッチ時刻 (epoch ms) を壁時計 (local time) で求める。

package/dist/time.js

@@ -1,319 +1,2 @@
-import { a as FlumeStartError, c as safeNormalizeError, i as safeNow, l as safeErrorMessage, n as safeInvokeCallback, o as FlumeParseError, r as FlumeLogger, s as attempt, t as FlumeSource } from "./flume-source.js";
-import { t as isRecord } from "./is-record.js";
-//#region lib/time/parse-cron-field.ts
-/**
-* 単一 cron フィールド (minute など) の spec を許可値の Set に展開する。
-* 対応: `*` / `* /n` / `a` / `a-b` / `a-b/n` とそれらのカンマ区切り。名前 (JAN, MON) は非対応
-*/
-function parseCronField(spec, min, max) {
-	const values = /* @__PURE__ */ new Set();
-	for (const part of spec.split(",")) {
-		const expanded = expandCronPart(part, min, max);
-		if (expanded instanceof FlumeParseError) return expanded;
-		for (const value of expanded) values.add(value);
-	}
-	if (values.size === 0) return new FlumeParseError(`cron field empty: "${spec}"`);
-	return values;
-}
-function expandCronPart(part, min, max) {
-	let range = part;
-	let step = 1;
-	const slash = part.indexOf("/");
-	if (slash !== -1) {
-		range = part.slice(0, slash);
-		const parsed = Number(part.slice(slash + 1));
-		if (!Number.isInteger(parsed) || parsed <= 0) return new FlumeParseError(`invalid cron step: "${part}"`);
-		step = parsed;
-	}
-	const bounds = resolveBounds(range, min, max);
-	if (bounds instanceof FlumeParseError) return bounds;
-	const numbers = [];
-	for (let value = bounds.lo; value <= bounds.hi; value += step) numbers.push(value);
-	return numbers;
-}
-function resolveBounds(range, min, max) {
-	if (range === "*") return {
-		lo: min,
-		hi: max
-	};
-	const dash = range.indexOf("-");
-	const lo = dash === -1 ? Number(range) : Number(range.slice(0, dash));
-	const hi = dash === -1 ? lo : Number(range.slice(dash + 1));
-	if (!Number.isInteger(lo) || !Number.isInteger(hi)) return new FlumeParseError(`invalid cron range: "${range}"`);
-	if (lo < min || hi > max || lo > hi) return new FlumeParseError(`cron value out of range [${min}-${max}]: "${range}"`);
-	return {
-		lo,
-		hi
-	};
-}
-//#endregion
-//#region lib/time/parse-cron.ts
-/**
-* 5 フィールド cron 式をパースする。dow は 0-7 を許可し 7 を 0 (日曜) に正規化する
-*/
-function parseCron(expression) {
-	const trimmed = expression.trim();
-	const fields = trimmed.split(/\s+/);
-	if (fields.length !== 5) return new FlumeParseError(`cron must have 5 fields, got ${fields.length}: "${expression}"`);
-	const minutes = parseCronField(fields[0] ?? "", 0, 59);
-	if (minutes instanceof FlumeParseError) return minutes;
-	const hours = parseCronField(fields[1] ?? "", 0, 23);
-	if (hours instanceof FlumeParseError) return hours;
-	const daysOfMonth = parseCronField(fields[2] ?? "", 1, 31);
-	if (daysOfMonth instanceof FlumeParseError) return daysOfMonth;
-	const months = parseCronField(fields[3] ?? "", 1, 12);
-	if (months instanceof FlumeParseError) return months;
-	const rawDaysOfWeek = parseCronField(fields[4] ?? "", 0, 7);
-	if (rawDaysOfWeek instanceof FlumeParseError) return rawDaysOfWeek;
-	const daysOfWeek = /* @__PURE__ */ new Set();
-	for (const value of rawDaysOfWeek) daysOfWeek.add(value === 7 ? 0 : value);
-	return {
-		source: trimmed,
-		minutes,
-		hours,
-		daysOfMonth,
-		months,
-		daysOfWeek,
-		domRestricted: fields[2] !== "*",
-		dowRestricted: fields[4] !== "*"
-	};
-}
-//#endregion
-//#region lib/time/cron-next.ts
-const MINUTE_MS = 6e4;
-const MAX_ITERATIONS = 5e5;
-/**
-* `afterMs` より後の最初の cron マッチ時刻 (epoch ms) を壁時計 (local time) で求める。
-* 到達不能なら FlumeParseError を返す
-*/
-function flumeCronNext(cron, afterMs) {
-	let candidate = Math.floor(afterMs / MINUTE_MS) * MINUTE_MS + MINUTE_MS;
-	for (let iteration = 0; iteration < MAX_ITERATIONS; iteration++) {
-		const date = new Date(candidate);
-		if (!cron.months.has(date.getMonth() + 1)) {
-			candidate = new Date(date.getFullYear(), date.getMonth() + 1, 1, 0, 0, 0, 0).getTime();
-			continue;
-		}
-		if (!matchesDay(cron, date)) {
-			candidate = new Date(date.getFullYear(), date.getMonth(), date.getDate() + 1, 0, 0, 0, 0).getTime();
-			continue;
-		}
-		if (!cron.hours.has(date.getHours())) {
-			candidate = new Date(date.getFullYear(), date.getMonth(), date.getDate(), date.getHours() + 1, 0, 0, 0).getTime();
-			continue;
-		}
-		if (!cron.minutes.has(date.getMinutes())) {
-			candidate += MINUTE_MS;
-			continue;
-		}
-		return candidate;
-	}
-	return new FlumeParseError(`cron "${cron.source}" has no next time within bound`);
-}
-function matchesDay(cron, date) {
-	const domMatch = cron.daysOfMonth.has(date.getDate());
-	const dowMatch = cron.daysOfWeek.has(date.getDay());
-	if (cron.domRestricted && cron.dowRestricted) return domMatch || dowMatch;
-	if (cron.domRestricted) return domMatch;
-	if (cron.dowRestricted) return dowMatch;
-	return true;
-}
-//#endregion
-//#region lib/time/time-scheduler.ts
-const MAX_TIMEOUT_MS = 2e9;
-const FIRE_TOLERANCE_MS = 1e3;
-/**
-* cron に従って `onTick` を駆動するタイマーループ。外部接続を持たないため reconnect 不要。
-* IO 境界は全て `attempt` 経由で扱い、停止後はコールバックを発火しない
-*/
-var FlumeTimeScheduler = class {
-	props;
-	log;
-	isStoppedFlag = false;
-	timer = null;
-	target = 0;
-	constructor(props) {
-		this.props = props;
-		this.log = new FlumeLogger({
-			source: "time.scheduler",
-			handler: props.onLog,
-			deps: props.deps
-		});
-	}
-	get isStopped() {
-		return this.isStoppedFlag;
-	}
-	start() {
-		const next = flumeCronNext(this.props.cron, safeNow({ deps: this.props.deps }));
-		if (next instanceof FlumeParseError) {
-			this.log.error({
-				action: "cron.no-next",
-				message: next.message,
-				error: next
-			});
-			return next;
-		}
-		this.target = next;
-		this.log.info({
-			action: "scheduler.start",
-			message: `next fire at ${new Date(next).toISOString()}`,
-			detail: { target: next }
-		});
-		this.arm();
-		return null;
-	}
-	stop() {
-		this.isStoppedFlag = true;
-		this.clearTimer();
-	}
-	arm() {
-		this.clearTimer();
-		const delay = Math.max(0, this.target - safeNow({ deps: this.props.deps }));
-		const capped = Math.min(delay, MAX_TIMEOUT_MS);
-		const result = attempt(() => this.props.deps.setTimeout(() => this.onWake(), capped));
-		if (result instanceof Error) {
-			this.log.error({
-				action: "scheduler.arm.error",
-				message: safeErrorMessage({ error: result }),
-				error: result
-			});
-			this.timer = null;
-			return;
-		}
-		this.timer = result;
-	}
-	onWake() {
-		this.timer = null;
-		if (this.isStoppedFlag) return;
-		if (this.target - safeNow({ deps: this.props.deps }) > FIRE_TOLERANCE_MS) {
-			this.arm();
-			return;
-		}
-		const firedAt = this.target;
-		safeInvokeCallback({
-			fn: () => this.props.onTick(firedAt),
-			onError: (error) => {
-				this.log.error({
-					action: "scheduler.tick.error",
-					message: safeErrorMessage({ error }),
-					error
-				});
-			}
-		});
-		const next = flumeCronNext(this.props.cron, firedAt);
-		if (next instanceof FlumeParseError) {
-			this.log.error({
-				action: "cron.no-next",
-				message: next.message,
-				error: next
-			});
-			return;
-		}
-		this.target = next;
-		this.arm();
-	}
-	clearTimer() {
-		if (this.timer === null) return;
-		const handle = this.timer;
-		const result = attempt(() => this.props.deps.clearTimeout(handle));
-		if (result instanceof Error) this.log.error({
-			action: "scheduler.timer.clear.error",
-			message: safeErrorMessage({ error: result }),
-			error: result
-		});
-		this.timer = null;
-	}
-};
-//#endregion
-//#region lib/time/time-source.ts
-/**
-* cron スケジュールで tick を emit する Source。外部接続を持たないため
-* 起動成功と同時に `connected` になり reconnect の対象外。
-* `options.message` で tick ごとの type / data / meta を上書きできる
-*/
-var FlumeTimeSource = class extends FlumeSource {
-	options;
-	name = "time";
-	scheduler = null;
-	constructor(options) {
-		super();
-		this.options = options;
-	}
-	async connect(ctx) {
-		this.setStatus("connecting");
-		const cron = parseCron(this.options.cron);
-		if (cron instanceof FlumeParseError) {
-			const error = new FlumeStartError(`Time source: invalid cron "${this.options.cron}": ${cron.message}`);
-			ctx.log.error({
-				action: "source.start.failed",
-				message: safeErrorMessage({ error }),
-				error
-			});
-			this.setStatus("disconnected", error.message);
-			return error;
-		}
-		this.scheduler = new FlumeTimeScheduler({
-			cron,
-			onLog: ctx.log.handler,
-			deps: ctx.deps,
-			onTick: (firedAt) => this.handleTick(ctx, firedAt)
-		});
-		const result = this.scheduler.start();
-		if (result instanceof Error) {
-			const error = new FlumeStartError(`Time source: ${safeErrorMessage({ error: result })}`);
-			this.setStatus("disconnected", error.message);
-			return error;
-		}
-		this.setStatus("connected");
-		return null;
-	}
-	disconnect() {
-		this.scheduler?.stop();
-		this.scheduler = null;
-	}
-	handleTick(ctx, firedAt) {
-		const tick = {
-			firedAt,
-			cron: this.options.cron
-		};
-		const custom = this.safeMessage(ctx, tick);
-		this.emit({
-			source: "time",
-			type: typeof custom.type === "string" ? custom.type : "tick",
-			data: isRecord(custom.data) ? custom.data : {
-				firedAt,
-				cron: this.options.cron
-			},
-			meta: this.normalizeMeta(custom.meta, this.options.cron),
-			receivedAt: safeNow({ deps: ctx.deps })
-		});
-	}
-	safeMessage(ctx, tick) {
-		const message = this.options.message;
-		if (!message) return {};
-		const result = attempt(() => message(tick));
-		if (result instanceof Error) {
-			const error = safeNormalizeError({ value: result });
-			ctx.log.warn({
-				action: "message.error",
-				message: safeErrorMessage({ error }),
-				error,
-				detail: { firedAt: tick.firedAt }
-			});
-			return {};
-		}
-		return isRecord(result) ? result : {};
-	}
-	normalizeMeta(meta, cron) {
-		if (!isRecord(meta)) return { cron };
-		const normalized = {};
-		for (const key of Object.keys(meta)) {
-			const value = meta[key];
-			if (typeof value === "string") normalized[key] = value;
-		}
-		if (Object.keys(normalized).length === 0) return { cron };
-		return normalized;
-	}
-};
-//#endregion
+import { i as parseCron, r as flumeCronNext, t as FlumeTimeSource } from "./time-source.js";
 export { FlumeTimeSource, flumeCronNext, parseCron };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@interactive-inc/flume",
-  "version": "0.9.4",
+  "version": "0.10.0",
   "description": "Unified notification listener for Discord, Slack, and GitHub. Raw WebSocket + fetch + Zod. No SDK dependencies.",
   "keywords": [
     "discord",

package/dist/parse-error.d.ts

@@ -1,9 +0,0 @@
-//#region lib/errors/parse-error.d.ts
-type Options = {
-  cause?: unknown;
-};
-declare class FlumeParseError extends Error {
-  constructor(message: string, options?: Options);
-}
-//#endregion
-export { FlumeParseError as t };