@interactive-inc/flume 0.10.0 → 0.11.0

package/dist/index.js

@@ -1,13 +1,14 @@
-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";
+import { a as safeInvokeCallback, c as FlumeParseError, d as safeErrorMessage, i as safeNow, l as attempt, n as FlumeSerialQueue, o as FlumeSourceReuseError, r as FlumeLogger, s as FlumeStartError, t as FlumeSource, u as safeNormalizeError } from "./flume-source.js";
+import { n as safeRandom, r as FlumeConnectionError, t as safeStringify } from "./safe-stringify.js";
+import { n as FlumeHttpError, t as safeReadText } from "./safe-read-text.js";
+import { t as isRecord } from "./is-record.js";
+import { t as safeJsonParse } from "./safe-json-parse.js";
 //#region lib/deps.ts
 /**
 * `globalThis.WebSocket` の現在の値を返す。
-* 取得は呼び出しごとに行う — `createFlumeDefaultDeps()` がモジュール初期化時ではなく
-* 呼ばれた瞬間の `globalThis.WebSocket` を見るので、jsdom / happy-dom / vitest の
-* `beforeEach` で `globalThis.WebSocket` を差し込むテスト戦略がそのまま機能する。
+* `createFlumeDefaultDeps()` が返す deps の `WebSocket` は getter でここへ委譲するため、
+* `new Flume()` 後に `globalThis.WebSocket` を差し込む (jsdom / happy-dom / vitest の
+* `beforeEach` パッチ) テスト戦略がそのまま機能する — 参照は常にアクセス時点の最新値。
 * `WebSocket` が無い環境 (Node の素の global など) では `null` を返す。
 */
 function resolveCurrentWebSocket() {
@@ -28,7 +29,9 @@ function resolveCurrentWebSocket() {
 function createFlumeDefaultDeps() {
 	return {
 		fetch: (url, init) => globalThis.fetch(url, init),
-		WebSocket: resolveCurrentWebSocket(),
+		get WebSocket() {
+			return resolveCurrentWebSocket();
+		},
 		now: () => Date.now(),
 		random: () => Math.random(),
 		setTimeout: (fn, ms) => globalThis.setTimeout(fn, ms),
@@ -39,20 +42,25 @@ function createFlumeDefaultDeps() {
 }
 //#endregion
 //#region lib/flume-stream.ts
-const DONE = {
-	value: void 0,
-	done: true
-};
+function doneResult() {
+	return {
+		value: void 0,
+		done: true
+	};
+}
 /**
 * push (`FlumeStreamHub.publish`) を pull (`for await`) に変換する async iterator。
 * consumer が待っていれば即 resolve、いなければ buffer に積み、溢れたら onOverflow に従う。
-* `return()` (break / 例外) と hub.close() のどちらでも自然に done へ落ちる
+* hub.close() ではバッファ済み item を吐き切ってから done へ落ちる (graceful tail drain)。
+* consumer 側の `return()` (break / 例外) はバッファを破棄して即 done になる (iterator 仕様)。
+* drop の観測は onDrop 経由 — drop 通知自体が firehose に還流して再帰しないよう初回のみ発火
 */
 var FlumeStream = class {
 	props;
 	items = [];
 	resolvers = [];
 	closed = false;
+	droppedCount = 0;
 	constructor(props) {
 		this.props = props;
 	}
@@ -67,6 +75,7 @@ var FlumeStream = class {
 			return;
 		}
 		if (this.items.length >= this.props.buffer) {
+			this.recordDrop();
 			if (this.props.onOverflow === "drop-newest") return;
 			this.items.shift();
 		}
@@ -77,7 +86,7 @@ var FlumeStream = class {
 		this.closed = true;
 		while (this.resolvers.length > 0) {
 			const resolver = this.resolvers.shift();
-			if (resolver) resolver(DONE);
+			if (resolver) resolver(doneResult());
 		}
 	}
 	next() {
@@ -86,42 +95,90 @@ var FlumeStream = class {
 			value: item,
 			done: false
 		});
-		if (this.closed) return Promise.resolve(DONE);
+		if (this.closed) return Promise.resolve(doneResult());
 		return new Promise((resolve) => this.resolvers.push(resolve));
 	}
 	return() {
+		this.items.splice(0);
+		this.close();
+		this.props.onClose();
+		return Promise.resolve(doneResult());
+	}
+	throw(error) {
+		this.items.splice(0);
 		this.close();
 		this.props.onClose();
-		return Promise.resolve(DONE);
+		return Promise.reject(error);
 	}
 	[Symbol.asyncIterator]() {
 		return this;
 	}
+	recordDrop() {
+		this.droppedCount++;
+		if (this.droppedCount > 1) return;
+		this.props.onDrop?.({ dropped: 1 });
+	}
 };
 //#endregion
 //#region lib/flume-stream-hub.ts
 const DEFAULT_BUFFER = 1e3;
 /**
+* NaN / Infinity / 0 以下を弾いて必ず 1 以上の有限整数にする。
+* 不正値で backpressure 上限が実質無効化される (比較が常に false → 無制限成長) のを防ぐ
+*/
+function sanitizeBufferSize(value) {
+	if (typeof value !== "number" || !Number.isFinite(value)) return DEFAULT_BUFFER;
+	if (value < 1) return 1;
+	return Math.floor(value);
+}
+/**
 * firehose (`onEvent` / `stream()`) の item を複数の pull consumer へ fan-out する内部ハブ。
 * subscriber が居なければ publish は実質 no-op。Flume 停止時に close() で全 stream を終端する
 */
 var FlumeStreamHub = class {
+	props;
 	streams = /* @__PURE__ */ new Set();
+	startupItems = [];
+	startupDropNotified = false;
+	hasSubscribed = false;
 	closed = false;
+	constructor(props = {}) {
+		this.props = props;
+	}
+	get isClosed() {
+		return this.closed;
+	}
 	publish(item) {
 		if (this.closed) return;
+		if (!this.hasSubscribed) {
+			if (this.startupItems.length >= DEFAULT_BUFFER) {
+				this.startupItems.shift();
+				if (!this.startupDropNotified) {
+					this.startupDropNotified = true;
+					this.props.onDrop?.({ dropped: 1 });
+				}
+			}
+			this.startupItems.push(item);
+			return;
+		}
 		for (const stream of this.streams) stream.push(item);
 	}
 	subscribe(options) {
 		const stream = new FlumeStream({
-			buffer: options?.buffer ?? DEFAULT_BUFFER,
+			buffer: sanitizeBufferSize(options?.buffer),
 			onOverflow: options?.onOverflow ?? "drop-oldest",
-			onClose: () => this.streams.delete(stream)
+			onClose: () => this.streams.delete(stream),
+			onDrop: this.props.onDrop
 		});
 		if (this.closed) {
 			stream.close();
 			return stream;
 		}
+		if (!this.hasSubscribed) {
+			this.hasSubscribed = true;
+			for (const item of this.startupItems) stream.push(item);
+			this.startupItems.splice(0);
+		}
 		this.streams.add(stream);
 		return stream;
 	}
@@ -130,6 +187,7 @@ var FlumeStreamHub = class {
 		this.closed = true;
 		for (const stream of this.streams) stream.close();
 		this.streams.clear();
+		this.startupItems.splice(0);
 	}
 };
 //#endregion
@@ -140,14 +198,16 @@ var FlumeStreamHub = class {
 * きれいに close したか / どれが失敗したか」を直接判定できる
 */
 var FlumeClosed = class {
-	props;
 	kind = "closed";
+	finalStatuses;
+	closeErrors;
 	constructor(props) {
-		this.props = props;
+		this.finalStatuses = Object.freeze(props.finalStatuses.map((status) => Object.freeze({ ...status })));
+		this.closeErrors = Object.freeze(props.closeErrors.map((closeError) => Object.freeze({ ...closeError })));
 		Object.freeze(this);
 	}
 	statuses() {
-		return this.props.finalStatuses;
+		return this.finalStatuses;
 	}
 	/**
 	* `runClose` 中に `source.stop()` が rejected で settle した source の名前と
@@ -155,7 +215,7 @@ var FlumeClosed = class {
 	* 全 source が clean close した場合は空配列。
 	*/
 	errors() {
-		return this.props.closeErrors;
+		return this.closeErrors;
 	}
 };
 //#endregion
@@ -163,7 +223,7 @@ var FlumeClosed = class {
 /**
 * 稼働中の Flume。close() で FlumeClosed へ遷移する。signal が abort されると自動 close。
 * 全ての source 呼び出し・signal 操作・status 読み取りを `attempt` 経由で扱い、
-* `runClose` の最外殻 try/catch で想定外の throw も `FlumeClosed` の resolve に変換する
+* `runClose` の最外殻でも `attempt` を通して想定外の throw を `FlumeClosed` の resolve に変換する
 */
 var FlumeRunning = class {
 	props;
@@ -201,88 +261,103 @@ var FlumeRunning = class {
 			}
 		}
 	}
+	/** Source の停止まで待つ。callback の完了は callback 外から drain() で待つ。 */
 	close() {
 		if (this.closePromise) return this.closePromise;
 		this.closePromise = this.runClose();
 		return this.closePromise;
 	}
+	/**
+	* 配送済み callback とその失敗診断が完了するまで待つ。通常は close() の後に呼ぶ。
+	* onEvent / onError 内では自身の完了待ちになるため呼ばない。
+	*/
+	async drain() {
+		if (this.closePromise) await this.closePromise;
+		await this.props.callbackQueue.drain();
+	}
 	statuses() {
 		return this.snapshotStatuses();
 	}
 	/**
 	* 統合 firehose を pull で受け取る async iterator。`for await (const item of running.stream())`。
 	* item は events + 全ログの union (`FlumeStreamItem`)。`item.kind` で判別する。
-	* close() / signal abort で iterator は自然に終了し、`break` すると hub から自動 unsubscribe する。
+	* close() / signal abort 後、callback の失敗診断まで配送して終了する。
+	* `break` すると hub から自動 unsubscribe する。
 	* consumer が遅れて buffer を超えたら `onOverflow` (既定 drop-oldest) に従う
 	*/
 	stream(options) {
 		return this.props.hub.subscribe(options);
 	}
 	/**
-	* Host が `Flume({ signal })` で渡した AbortSignal をそのまま公開する。
+	* `Flume({ signal })` に渡された AbortSignal をそのまま公開する。
 	* 直接の controller を持っていない呼び出し元が `running.signal?.aborted`
-	* で abort 状態を確認できる
+	* で abort 状態を確認できる。`FlumeConfluence` 経由で開かれたグループでは
+	* host の signal ではなく confluence 内部の timeout controller の signal になる点に注意
 	*/
 	get signal() {
 		return this.props.signal;
 	}
 	async runClose() {
 		const closeErrors = [];
-		try {
-			this.props.log.info({
-				action: "flume.close",
-				message: `closing ${this.props.sources.length} source(s)`
-			});
-			const settled = await Promise.allSettled(this.props.sources.map((source) => Promise.resolve().then(() => source.stop())));
-			for (const [index, result] of settled.entries()) if (result.status === "rejected") {
-				const source = this.props.sources[index];
-				const name = source ? this.sourceName(source) : "?";
-				const error = safeNormalizeError({ value: result.reason });
-				closeErrors.push({
-					source: name,
-					error
-				});
-				this.props.log.error({
-					action: "flume.close.failed",
-					message: `${name}: ${safeErrorMessage({ error })}`,
-					error,
-					detail: { source: name }
-				});
-			}
-			const signal = this.props.signal;
-			if (signal) {
-				const result = attempt(() => signal.removeEventListener("abort", this.onAbort));
-				if (result instanceof Error) {
-					const error = safeNormalizeError({ value: result });
-					this.props.log.error({
-						action: "signal.removeListener.failed",
-						message: safeErrorMessage({ error }),
-						error
-					});
-				}
-			}
-			this.props.log.info({
-				action: "flume.close.complete",
-				message: "all sources closed"
-			});
-			this.props.hub.close();
-			return new FlumeClosed({
-				finalStatuses: this.snapshotStatuses(),
-				closeErrors
-			});
-		} catch (err) {
-			const error = safeNormalizeError({ value: err });
+		const result = await attempt(() => this.closeSources(closeErrors));
+		if (result instanceof Error) {
+			const error = safeNormalizeError({ value: result });
 			this.props.log.error({
 				action: "flume.close.unhandled",
 				message: safeErrorMessage({ error }),
 				error
 			});
-			this.props.hub.close();
-			return new FlumeClosed({
-				finalStatuses: this.snapshotStatuses(),
-				closeErrors
+		}
+		const sealed = attempt(() => this.props.seal());
+		if (sealed instanceof Error) this.props.log.error({
+			action: "flume.close.seal.failed",
+			message: safeErrorMessage({ error: sealed }),
+			error: sealed
+		});
+		this.props.callbackQueue.drain().then(() => this.props.hub.close());
+		return new FlumeClosed({
+			finalStatuses: this.snapshotStatuses(),
+			closeErrors
+		});
+	}
+	async closeSources(closeErrors) {
+		this.props.log.info({
+			action: "flume.close",
+			message: `closing ${this.props.sources.length} source(s)`
+		});
+		const settled = await Promise.allSettled(this.props.sources.map((source) => Promise.resolve().then(() => source.stop())));
+		for (const [index, result] of settled.entries()) {
+			const source = this.props.sources[index];
+			const name = source ? this.sourceName(source) : "?";
+			const error = result.status === "rejected" ? safeNormalizeError({ value: result.reason }) : result.value instanceof Error ? result.value : null;
+			if (error === null) continue;
+			closeErrors.push({
+				source: name,
+				error
+			});
+			this.props.log.error({
+				action: "flume.close.failed",
+				message: `${name}: ${safeErrorMessage({ error })}`,
+				error,
+				detail: { source: name }
 			});
 		}
+		const signal = this.props.signal;
+		if (signal) {
+			const result = attempt(() => signal.removeEventListener("abort", this.onAbort));
+			if (result instanceof Error) {
+				const error = safeNormalizeError({ value: result });
+				this.props.log.error({
+					action: "signal.removeListener.failed",
+					message: safeErrorMessage({ error }),
+					error
+				});
+			}
+		}
+		this.props.log.info({
+			action: "flume.close.complete",
+			message: "all sources closed"
+		});
 	}
 	snapshotStatuses() {
 		return this.props.sources.map((source) => {
@@ -321,12 +396,42 @@ const DEFAULTS = {
 	baseDelay: 1e3,
 	maxDelay: 3e4
 };
+/**
+* `baseDelay` として受理できる値のみ透過する。NaN / Infinity / 1ms 未満 /
+* 非数値 / 明示的 `undefined` (spread でデフォルトを潰すケース) は既定値へ落とす。
+* 0 や負値を許すと `maxAttempts: Infinity` と組み合わさって 0ms 再接続ホットループになる
+*/
+function sanitizeBaseDelay(value) {
+	if (typeof value !== "number" || !Number.isFinite(value)) return DEFAULTS.baseDelay;
+	if (value < 1) return DEFAULTS.baseDelay;
+	return value;
+}
+function sanitizeMaxDelay(value, baseDelay) {
+	if (typeof value !== "number" || !Number.isFinite(value)) return Math.max(DEFAULTS.maxDelay, baseDelay);
+	if (value < baseDelay) return baseDelay;
+	return value;
+}
+/** 1 以上の整数 or Infinity のみ透過。NaN / 0 / 負値 / 小数は既定 (Infinity) へ */
+function sanitizeMaxAttempts(value) {
+	if (typeof value !== "number" || Number.isNaN(value)) return DEFAULTS.maxAttempts;
+	if (value === Infinity) return Infinity;
+	if (!Number.isInteger(value) || value < 1) return DEFAULTS.maxAttempts;
+	return value;
+}
+/**
+* ユーザー入力の reconnect 指定を検証済み `FlumeReconnectConfig` へ解決する。
+* `false` / `undefined` は再接続無効 (null)。`true` は既定値。
+* オブジェクトはフィールドごとに検証し、不正値 (NaN / 負値 / Infinity delay 等) は
+* 既定値へフォールバックする — throw しない
+*/
 function resolveFlumeReconnectConfig(input) {
 	if (input === false || input === void 0) return null;
 	if (input === true) return { ...DEFAULTS };
+	const baseDelay = sanitizeBaseDelay(input.baseDelay);
 	return {
-		...DEFAULTS,
-		...input
+		maxAttempts: sanitizeMaxAttempts(input.maxAttempts),
+		baseDelay,
+		maxDelay: sanitizeMaxDelay(input.maxDelay, baseDelay)
 	};
 }
 //#endregion
@@ -335,59 +440,152 @@ function resolveFlumeReconnectConfig(input) {
 * 起動前の Flume。`open()` で `FlumeRunning` へ遷移する。
 * コンストラクタは単一オブジェクト `{ sources, ...options }` を受け取る (`sources` のみ必須)。
 * events も全ログも 1 本の firehose (`onEvent` push / `stream()` pull) に流れ、購読側が filter する。
-* いずれかの source 失敗時は既に成功した source を全て `stop()` してロールバックし
-* `FlumeStartError` を返す。
+* 起動失敗時はこの open が取得した source を `stop()` してロールバックする。
+* 半接続状態で失敗した source も含むが、再利用を拒否した source は他の所有者のため停止しない。
 * `source.start()` / `source.stop()` の sync throw も `Promise.resolve().then` 経由で
 * Promise rejection に正規化して `allSettled` で捕捉する (`open()` は決して reject しない)
 */
 var Flume = class {
 	options;
 	consumed = false;
+	isAcceptingItems = true;
 	log;
 	deps;
 	sources;
 	sourceEventHandler;
-	hub = new FlumeStreamHub();
+	hub;
+	callbackQueue = new FlumeSerialQueue();
 	constructor(options) {
 		this.options = options;
-		this.sources = options.sources;
+		this.sources = [...options.sources];
 		this.deps = options.deps ?? createFlumeDefaultDeps();
+		this.hub = new FlumeStreamHub({ onDrop: () => this.notifyStreamOverflow() });
 		this.log = new FlumeLogger({
 			source: "flume",
 			handler: this.buildLogHandler(),
 			deps: this.deps
 		});
-		this.sourceEventHandler = (event) => this.emitItem({
-			kind: "event",
-			event
+		this.sourceEventHandler = (event) => {
+			this.emitItem({
+				kind: "event",
+				event
+			});
+		};
+	}
+	/**
+	* stream の buffer 溢れ通知 (stream ごとに初回 1 回)。
+	* firehose (hub) には流さない — 溢れている stream 自身に還流して実イベントを
+	* さらに追い出す自己破壊になるため、push の `onEvent` にだけ warn log として届ける
+	*/
+	notifyStreamOverflow() {
+		const log = {
+			level: "warn",
+			source: "flume",
+			action: "stream.overflow",
+			message: "stream buffer overflowed, dropping items (notified once per stream; see FlumeStreamOptions.buffer)",
+			timestamp: safeNow({ deps: this.deps })
+		};
+		this.enqueueCallback({
+			kind: "log",
+			log
 		});
 	}
 	/** source が受信したログを firehose へ流す handler。error は onError にも分岐する */
 	buildLogHandler() {
 		return (log) => {
+			if (!this.isAcceptingItems) return;
 			this.emitItem({
 				kind: "log",
 				log
 			});
-			const onError = this.options.onError;
-			if (!onError || log.level !== "error") return;
-			try {
-				Promise.resolve(onError(log)).catch(() => {});
-			} catch {}
+			if (log.level === "error") this.invokeOnError(log);
 		};
 	}
 	/**
 	* firehose の単一 sink: pull の hub と push の onEvent の両方へ item を配る。
-	* onEvent への転送は this.log を経由しない (経由すると log item 経路で再帰する) ため
-	* 例外をここで握り潰す
+	* close 後の遅延 emit (stop 中の straggler) は push 側にも流さない (pull 側と対称にする)。
+	* onEvent への転送は this.log を経由しない (経由すると log item 経路で再帰する)。
+	* callback failure は reportCallbackFailure が pull hub と peer callback へ直接診断する。
 	*/
 	emitItem(item) {
+		if (!this.isAcceptingItems || this.hub.isClosed) return Promise.resolve();
 		this.hub.publish(item);
-		const onEvent = this.options.onEvent;
-		if (!onEvent) return;
-		try {
-			Promise.resolve(onEvent(item)).catch(() => {});
-		} catch {}
+		return this.enqueueCallback(item);
+	}
+	enqueueCallback(item, notifyPeerOnFailure = true) {
+		const onEventResult = attempt(() => this.options.onEvent);
+		if (onEventResult instanceof Error) {
+			this.reportCallbackFailure("onEvent", onEventResult, notifyPeerOnFailure, item);
+			return Promise.resolve();
+		}
+		if (!onEventResult) return Promise.resolve();
+		return this.callbackQueue.add(async () => {
+			const result = await attempt(() => Promise.resolve(onEventResult(item)));
+			if (result instanceof Error) this.reportCallbackFailure("onEvent", result, notifyPeerOnFailure, item);
+		});
+	}
+	/**
+	* error log 専用 sink も callbackQueue に載せ、drain() が in-flight callback と
+	* その失敗診断まで drain できるようにする
+	*/
+	invokeOnError(log, notifyPeerOnFailure = true) {
+		const onErrorResult = attempt(() => this.options.onError);
+		if (onErrorResult instanceof Error) {
+			this.reportCallbackFailure("onError", onErrorResult, notifyPeerOnFailure, {
+				kind: "log",
+				log
+			});
+			return Promise.resolve();
+		}
+		if (!onErrorResult) return Promise.resolve();
+		return this.callbackQueue.add(async () => {
+			const result = await attempt(() => Promise.resolve(onErrorResult(log)));
+			if (result instanceof Error) this.reportCallbackFailure("onError", result, notifyPeerOnFailure, {
+				kind: "log",
+				log
+			});
+		});
+	}
+	/**
+	* 観測 sink 自身の失敗は同じ sink へ戻すと再帰するため、まず pull stream へ直接 publish し、
+	* もう一方の callback にだけ転送する。peer も失敗した場合は hub-only の診断を残して終端する
+	*/
+	reportCallbackFailure(callback, error, notifyPeer, failedItem) {
+		const itemDetail = failedItem?.kind === "event" ? {
+			itemKind: failedItem.kind,
+			itemSource: failedItem.event.source,
+			itemType: failedItem.event.type
+		} : failedItem?.kind === "log" ? {
+			itemKind: failedItem.kind,
+			itemSource: failedItem.log.source,
+			itemAction: failedItem.log.action,
+			itemDetail: failedItem.log.detail
+		} : {};
+		const log = {
+			level: "error",
+			source: "flume",
+			action: `${callback}.error`,
+			message: `${callback} callback failed: ${safeErrorMessage({ error })}`,
+			error,
+			detail: {
+				callback,
+				...itemDetail
+			},
+			timestamp: safeNow({ deps: this.deps })
+		};
+		this.hub.publish({
+			kind: "log",
+			log
+		});
+		if (!notifyPeer) return;
+		if (callback === "onEvent") {
+			this.invokeOnError(log, false);
+			return;
+		}
+		this.enqueueCallback({
+			kind: "log",
+			log
+		}, false);
 	}
 	async open() {
 		const guard = this.guardOpen();
@@ -398,14 +596,15 @@ var Flume = class {
 			message: `opening ${this.sources.length} source(s)`,
 			detail: { count: this.sources.length }
 		});
-		const reconnect = resolveFlumeReconnectConfig(this.options.reconnect);
+		const reconnect = this.resolveReconnect();
 		const settled = await Promise.allSettled(this.sources.map((source) => this.safeStart(source, reconnect)));
 		const failures = [];
-		const started = [];
+		const ownedSources = /* @__PURE__ */ new Set();
 		for (const [index, result] of settled.entries()) {
 			const source = this.sources[index];
 			if (source === void 0) continue;
 			const name = this.sourceName(source);
+			if (!((result.status === "rejected" ? result.reason : result.value) instanceof FlumeSourceReuseError)) ownedSources.add(source);
 			if (result.status === "rejected") {
 				failures.push({
 					name,
@@ -413,14 +612,10 @@ var Flume = class {
 				});
 				continue;
 			}
-			if (result.value instanceof Error) {
-				failures.push({
-					name,
-					error: result.value
-				});
-				continue;
-			}
-			started.push(source);
+			if (result.value instanceof Error) failures.push({
+				name,
+				error: result.value
+			});
 		}
 		if (failures.length > 0) {
 			for (const failure of failures) this.log.error({
@@ -429,7 +624,7 @@ var Flume = class {
 				error: failure.error,
 				detail: { source: failure.name }
 			});
-			await this.rollback(started);
+			await this.rollback([...ownedSources]);
 			const detail = failures.map((f) => `${f.name}: ${safeErrorMessage({ error: f.error })}`).join("; ");
 			const error = new FlumeStartError(`Flume.open: ${failures.length} source(s) failed: ${detail}`);
 			this.log.error({
@@ -437,28 +632,48 @@ var Flume = class {
 				message: safeErrorMessage({ error }),
 				error
 			});
+			this.finishFailedOpen();
 			return error;
 		}
 		if (this.isSignalAborted()) {
-			await this.rollback(this.sources);
+			await this.rollback([...ownedSources]);
 			const error = new FlumeStartError("Flume.open: aborted during open");
 			this.log.warn({
 				action: "flume.open.aborted",
 				message: safeErrorMessage({ error }),
 				error
 			});
+			this.finishFailedOpen();
 			return error;
 		}
 		this.log.info({
 			action: "flume.open.complete",
 			message: "all sources opened"
 		});
-		return new FlumeRunning({
+		const running = new FlumeRunning({
 			sources: this.sources,
 			signal: this.options.signal,
 			log: this.log,
-			hub: this.hub
+			hub: this.hub,
+			callbackQueue: this.callbackQueue,
+			seal: () => {
+				this.isAcceptingItems = false;
+			}
+		});
+		if (!this.isSignalAborted()) return running;
+		await running.close();
+		const error = new FlumeStartError("Flume.open: aborted while entering running state");
+		this.log.warn({
+			action: "flume.open.aborted",
+			message: safeErrorMessage({ error }),
+			error
 		});
+		return error;
+	}
+	/** 起動失敗の戻り値は callback を待たず、配送済み診断の完了後に hub を閉じる。 */
+	finishFailedOpen() {
+		this.isAcceptingItems = false;
+		this.callbackQueue.drain().then(() => this.hub.close());
 	}
 	guardOpen() {
 		if (this.consumed) {
@@ -481,6 +696,19 @@ var Flume = class {
 		}
 		return null;
 	}
+	/** reconnect オプションの解決。throwing getter を持つ hostile 入力でも open() を reject させない */
+	resolveReconnect() {
+		const result = attempt(() => resolveFlumeReconnectConfig(this.options.reconnect));
+		if (result instanceof Error) {
+			this.log.warn({
+				action: "reconnect.config.invalid",
+				message: safeErrorMessage({ error: result }),
+				error: result
+			});
+			return null;
+		}
+		return result;
+	}
 	isSignalAborted() {
 		const signal = this.options.signal;
 		if (!signal) return false;
@@ -506,18 +734,25 @@ var Flume = class {
 	}
 	async rollback(sources) {
 		const settled = await Promise.allSettled(sources.map((source) => Promise.resolve().then(() => source.stop())));
-		for (const [index, result] of settled.entries()) if (result.status === "rejected") {
+		for (const [index, result] of settled.entries()) {
 			const source = sources[index];
 			const name = source ? this.sourceName(source) : "?";
-			const error = safeNormalizeError({ value: result.reason });
-			this.log.error({
-				action: "flume.rollback.failed",
-				message: `${name}: ${safeErrorMessage({ error })}`,
-				error,
-				detail: { source: name }
-			});
+			if (result.status === "rejected") {
+				const error = safeNormalizeError({ value: result.reason });
+				this.logRollbackFailure(name, error);
+				continue;
+			}
+			if (result.value instanceof Error) this.logRollbackFailure(name, result.value);
 		}
 	}
+	logRollbackFailure(name, error) {
+		this.log.error({
+			action: "flume.rollback.failed",
+			message: `${name}: ${safeErrorMessage({ error })}`,
+			error,
+			detail: { source: name }
+		});
+	}
 };
 //#endregion
 //#region lib/flume-confluence.ts
@@ -531,28 +766,61 @@ const DEFAULT_REPLACE_TIMEOUT_MS = 1e4;
 * `replace(id, sources)` は同じ id のグループを差し替える。新グループを先に起動し、
 * 起動成功時にのみ旧グループを停止するので連続稼働を維持できる (token rotation 用途)。
 * 起動失敗時は旧グループはそのまま走り続ける。
+* 注意: 失敗した replace / add に渡した source インスタンスは consumed になるため、
+* リトライには新しいインスタンスを構築する必要がある。
+*
+* `closeAll()` は終端操作。以後の `add()` / `replace()` は拒否され、closeAll と並行して
+* 起動中だったグループも abort して完了を待つ (シャットダウン後に誰にも止められない
+* グループが残らない)。
 *
 * throw しない流儀に従い `add()` / `replace()` は `Error | null` を返す
 */
 var FlumeConfluence = class {
 	props;
 	running = /* @__PURE__ */ new Map();
+	/** open() を await 中でまだ Map に commit されていないグループの id (add 重複と remove 追跡用) */
+	pendingIds = /* @__PURE__ */ new Set();
+	removedWhilePending = /* @__PURE__ */ new Set();
+	pendingOpens = /* @__PURE__ */ new Set();
+	isClosedFlag = false;
 	deps;
 	constructor(props = {}) {
 		this.props = props;
 		this.deps = props.deps ?? createFlumeDefaultDeps();
 	}
+	get isClosed() {
+		return this.isClosedFlag;
+	}
 	/** 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 this.openGroup(id, sources, void 0);
-		if (running instanceof Error) return running;
-		if (this.running.has(id)) {
-			await running.close();
-			return new FlumeStartError(`FlumeConfluence: id already added: ${id}`);
+		if (this.isClosedFlag) return new FlumeStartError(`FlumeConfluence: already closed: ${id}`);
+		if (this.running.has(id) || this.pendingIds.has(id)) return new FlumeStartError(`FlumeConfluence: id already added: ${id}`);
+		this.pendingIds.add(id);
+		const pending = this.createPendingOpen();
+		this.pendingOpens.add(pending);
+		try {
+			const running = await this.openGroup(id, sources, pending.controller, void 0);
+			if (running instanceof Error) return running;
+			if (this.isClosedFlag) {
+				await running.close();
+				return new FlumeStartError(`FlumeConfluence: closed during add: ${id}`);
+			}
+			if (this.removedWhilePending.has(id)) {
+				await running.close();
+				return new FlumeStartError(`FlumeConfluence: removed during add: ${id}`);
+			}
+			if (this.running.has(id)) {
+				await running.close();
+				return new FlumeStartError(`FlumeConfluence: id already added: ${id}`);
+			}
+			this.running.set(id, running);
+			return null;
+		} finally {
+			this.pendingIds.delete(id);
+			this.removedWhilePending.delete(id);
+			this.pendingOpens.delete(pending);
+			pending.finish();
 		}
-		this.running.set(id, running);
-		return null;
 	}
 	/**
 	* 既存グループを新しい sources で差し替える。新グループを先に起動し、成功時のみ旧を停止する。
@@ -560,27 +828,48 @@ var FlumeConfluence = class {
 	* 旧グループが存在しない場合は `Error` を返す (replace は add と違ってグループの存在を前提とする)
 	*/
 	async replace(id, sources, options) {
+		if (this.isClosedFlag) return new FlumeStartError(`FlumeConfluence: already closed: ${id}`);
 		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`);
+		const pending = this.createPendingOpen();
+		this.pendingOpens.add(pending);
+		try {
+			const timeoutMs = options?.replaceTimeoutMs ?? DEFAULT_REPLACE_TIMEOUT_MS;
+			const next = await this.openGroup(id, sources, pending.controller, timeoutMs);
+			if (next instanceof Error) return next;
+			if (this.isClosedFlag) {
+				await next.close();
+				return new FlumeStartError(`FlumeConfluence: closed during replace: ${id}`);
+			}
+			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;
+		} finally {
+			this.pendingOpens.delete(pending);
+			pending.finish();
 		}
-		this.running.set(id, next);
-		await previous.close();
-		return null;
 	}
-	/** 指定グループだけ close。他グループは無停止。未知の id は no-op */
+	/**
+	* 指定グループだけ close。他グループは無停止。未知の id は no-op。
+	* 起動中 (add が open を await 中) の id は commit 時点で破棄されるよう予約する
+	*/
 	async remove(id) {
+		if (this.pendingIds.has(id)) this.removedWhilePending.add(id);
 		const running = this.running.get(id);
 		if (!running) return;
 		this.running.delete(id);
 		await running.close();
 	}
+	/** 終端操作。全グループを close し、以後の add / replace を拒否する */
 	async closeAll() {
+		this.isClosedFlag = true;
+		const pending = [...this.pendingOpens];
+		for (const operation of pending) attempt(() => operation.controller.abort());
+		await Promise.allSettled(pending.map((operation) => operation.done));
 		const ids = [...this.running.keys()];
 		await Promise.all(ids.map((id) => this.remove(id)));
 	}
@@ -591,38 +880,66 @@ var FlumeConfluence = class {
 		return [...this.running.keys()];
 	}
 	/**
-	* 1 グループ分の Flume を開いて FlumeRunning を返す。timeoutMs を指定すると open() を
-	* AbortSignal でレース掛けし、超過時に新グループ起動を中止する。失敗時の rollback は
-	* Flume 本体に任せる
+	* 1 グループ分の Flume を開いて FlumeRunning を返す。timeoutMs を指定すると AbortSignal を
+	* ctx.signal として各 source へ注入し、超過時に abort して進行中の connect ごと中止する
+	* (source 側は base クラスが signal を購読して stop() を発火する)。
+	* 失敗時の 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({
+	async openGroup(id, sources, controller, timeoutMs) {
+		const timeoutState = { isArmed: timeoutMs !== void 0 };
+		const timeoutResult = timeoutMs === void 0 ? null : attempt(() => this.deps.setTimeout(() => {
+			if (timeoutState.isArmed) controller.abort();
+		}, timeoutMs));
+		if (timeoutResult instanceof Error) {
+			attempt(() => controller.abort());
+			return new FlumeStartError(`FlumeConfluence: failed to schedule timeout for "${id}"`, { cause: timeoutResult });
+		}
+		const flume = new Flume({
 			sources,
 			onEvent: this.wrapOnEvent(id),
-			onError: this.props.onError,
+			onError: this.wrapOnError(id),
 			deps: this.props.deps,
 			reconnect: this.props.reconnect,
-			signal: controller?.signal
-		}).open();
-		if (timeoutHandle !== null) this.deps.clearTimeout(timeoutHandle);
+			signal: controller.signal
+		});
+		const result = await attempt(() => flume.open());
+		timeoutState.isArmed = false;
+		if (timeoutResult !== null) attempt(() => this.deps.clearTimeout(timeoutResult));
 		if (result instanceof Error) {
-			if (controller !== null && controller.signal.aborted) return new FlumeStartError(`FlumeConfluence: open of "${id}" timed out after ${timeoutMs}ms`);
+			if (controller.signal.aborted && timeoutMs !== void 0) return new FlumeStartError(`FlumeConfluence: open of "${id}" timed out after ${timeoutMs}ms`, { cause: result });
 			return result;
 		}
 		return result;
 	}
+	createPendingOpen() {
+		const completion = Promise.withResolvers();
+		return {
+			controller: new AbortController(),
+			done: completion.promise,
+			finish: completion.resolve
+		};
+	}
 	wrapOnEvent(id) {
 		const onEvent = this.props.onEvent;
 		if (!onEvent) return void 0;
 		return (item) => {
-			onEvent({
+			return onEvent({
 				...item,
 				groupId: id
 			});
 		};
 	}
+	wrapOnError(id) {
+		const onError = this.props.onError;
+		if (!onError) return void 0;
+		return (log) => onError({
+			...log,
+			detail: {
+				...log.detail,
+				groupId: id
+			}
+		});
+	}
 };
 //#endregion
-export { Flume, FlumeClosed, FlumeConfluence, FlumeConnectionError, FlumeHttpError, FlumeParseError, FlumeRunning, FlumeSource, FlumeStartError, FlumeTimeSource, createFlumeDefaultDeps, flumeCollectCatchupMatches };
+export { Flume, FlumeClosed, FlumeConfluence, FlumeConnectionError, FlumeHttpError, FlumeParseError, FlumeRunning, FlumeSource, FlumeStartError, attempt, createFlumeDefaultDeps, isRecord, safeErrorMessage, safeInvokeCallback, safeJsonParse, safeNormalizeError, safeNow, safeRandom, safeReadText, safeStringify };