@interactive-inc/flume 0.9.4 → 0.10.1

package/dist/index.js

@@ -1,12 +1,12 @@
-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 { a as safeNow, c as attempt, i as FlumeLogger, l as safeNormalizeError, n as FlumeSerialQueue, o as FlumeStartError, r as safeInvokeCallback, s as FlumeParseError, t as FlumeSource, u as safeErrorMessage } from "./flume-source.js";
 import { t as FlumeConnectionError } from "./connection-error.js";
 import { t as FlumeHttpError } from "./http-error.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() {
@@ -27,7 +27,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),
@@ -38,20 +40,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;
 	}
@@ -66,6 +73,7 @@ var FlumeStream = class {
 			return;
 		}
 		if (this.items.length >= this.props.buffer) {
+			this.recordDrop();
 			if (this.props.onOverflow === "drop-newest") return;
 			this.items.shift();
 		}
@@ -76,51 +84,102 @@ var FlumeStream = class {
 		this.closed = true;
 		while (this.resolvers.length > 0) {
 			const resolver = this.resolvers.shift();
-			if (resolver) resolver(DONE);
+			if (resolver) resolver(doneResult());
 		}
 	}
+	get dropped() {
+		return this.droppedCount;
+	}
 	next() {
 		const item = this.items.shift();
 		if (item !== void 0) return Promise.resolve({
 			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;
 	}
@@ -129,6 +188,7 @@ var FlumeStreamHub = class {
 		this.closed = true;
 		for (const stream of this.streams) stream.close();
 		this.streams.clear();
+		this.startupItems.splice(0);
 	}
 };
 //#endregion
@@ -139,14 +199,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 の名前と
@@ -154,7 +216,7 @@ var FlumeClosed = class {
 	* 全 source が clean close した場合は空配列。
 	*/
 	errors() {
-		return this.props.closeErrors;
+		return this.closeErrors;
 	}
 };
 //#endregion
@@ -218,9 +280,10 @@ var FlumeRunning = class {
 		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;
@@ -233,10 +296,11 @@ var FlumeRunning = class {
 				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") {
+			for (const [index, result] of settled.entries()) {
 				const source = this.props.sources[index];
 				const name = source ? this.sourceName(source) : "?";
-				const error = safeNormalizeError({ value: result.reason });
+				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
@@ -260,10 +324,12 @@ var FlumeRunning = class {
 					});
 				}
 			}
+			await this.props.callbackQueue.drain();
 			this.props.log.info({
 				action: "flume.close.complete",
 				message: "all sources closed"
 			});
+			await this.props.callbackQueue.drain();
 			this.props.hub.close();
 			return new FlumeClosed({
 				finalStatuses: this.snapshotStatuses(),
@@ -320,12 +386,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
@@ -334,8 +430,8 @@ function resolveFlumeReconnectConfig(input) {
 * 起動前の Flume。`open()` で `FlumeRunning` へ遷移する。
 * コンストラクタは単一オブジェクト `{ sources, ...options }` を受け取る (`sources` のみ必須)。
 * events も全ログも 1 本の firehose (`onEvent` push / `stream()` pull) に流れ、購読側が filter する。
-* いずれかの source 失敗時は既に成功した source を全て `stop()` してロールバックし
-* `FlumeStartError` を返す。
+* いずれかの source 失敗時は全 source を `stop()` してロールバックし `FlumeStartError` を返す
+* (失敗した source も半接続状態のリソースを持ち得るため、成功分だけでなく全数を stop する)。
 * `source.start()` / `source.stop()` の sync throw も `Promise.resolve().then` 経由で
 * Promise rejection に正規化して `allSettled` で捕捉する (`open()` は決して reject しない)
 */
@@ -346,11 +442,13 @@ var Flume = class {
 	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(),
@@ -361,6 +459,25 @@ var Flume = class {
 			event
 		});
 	}
+	/**
+	* stream の buffer 溢れ通知 (stream ごとに初回 1 回)。
+	* firehose (hub) には流さない — 溢れている stream 自身に還流して実イベントを
+	* さらに追い出す自己破壊になるため、push の `onEvent` にだけ warn log として届ける
+	*/
+	notifyStreamOverflow() {
+		if (!this.options.onEvent) return;
+		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) => {
@@ -377,16 +494,21 @@ var Flume = class {
 	}
 	/**
 	* firehose の単一 sink: pull の hub と push の onEvent の両方へ item を配る。
+	* close 後の遅延 emit (stop 中の straggler) は push 側にも流さない (pull 側と対称にする)。
 	* onEvent への転送は this.log を経由しない (経由すると log item 経路で再帰する) ため
 	* 例外をここで握り潰す
 	*/
 	emitItem(item) {
+		if (this.hub.isClosed) return Promise.resolve();
 		this.hub.publish(item);
+		return this.enqueueCallback(item);
+	}
+	enqueueCallback(item) {
 		const onEvent = this.options.onEvent;
-		if (!onEvent) return;
-		try {
-			Promise.resolve(onEvent(item)).catch(() => {});
-		} catch {}
+		if (!onEvent) return Promise.resolve();
+		return this.callbackQueue.add(async () => {
+			await attempt(() => Promise.resolve(onEvent(item)));
+		});
 	}
 	async open() {
 		const guard = this.guardOpen();
@@ -397,10 +519,9 @@ 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 = [];
 		for (const [index, result] of settled.entries()) {
 			const source = this.sources[index];
 			if (source === void 0) continue;
@@ -412,14 +533,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({
@@ -428,7 +545,7 @@ var Flume = class {
 				error: failure.error,
 				detail: { source: failure.name }
 			});
-			await this.rollback(started);
+			await this.rollback(this.sources);
 			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({
@@ -436,6 +553,7 @@ var Flume = class {
 				message: safeErrorMessage({ error }),
 				error
 			});
+			await this.callbackQueue.drain();
 			return error;
 		}
 		if (this.isSignalAborted()) {
@@ -446,18 +564,42 @@ var Flume = class {
 				message: safeErrorMessage({ error }),
 				error
 			});
+			await this.callbackQueue.drain();
 			return error;
 		}
 		this.log.info({
 			action: "flume.open.complete",
 			message: "all sources opened"
 		});
-		return new FlumeRunning({
+		await this.callbackQueue.drain();
+		if (this.isSignalAborted()) {
+			await this.rollback(this.sources);
+			const error = new FlumeStartError("Flume.open: aborted during completion");
+			this.log.warn({
+				action: "flume.open.aborted",
+				message: safeErrorMessage({ error }),
+				error
+			});
+			await this.callbackQueue.drain();
+			return error;
+		}
+		const running = new FlumeRunning({
 			sources: this.sources,
 			signal: this.options.signal,
 			log: this.log,
-			hub: this.hub
+			hub: this.hub,
+			callbackQueue: this.callbackQueue
+		});
+		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
 		});
+		await this.callbackQueue.drain();
+		return error;
 	}
 	guardOpen() {
 		if (this.consumed) {
@@ -480,6 +622,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;
@@ -505,61 +660,142 @@ 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
+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 用途)。
+* 起動失敗時は旧グループはそのまま走り続ける。
+* 注意: 失敗した 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 new Flume({
-			sources,
-			onEvent: this.props.onEvent,
-			onError: this.props.onError,
-			deps: this.props.deps,
-			reconnect: this.props.reconnect
-		}).open();
-		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();
+		}
+	}
+	/**
+	* 既存グループを新しい sources で差し替える。新グループを先に起動し、成功時のみ旧を停止する。
+	* 起動失敗 / replaceTimeoutMs (既定 10s) 経過時は新グループを破棄し旧を走らせたまま返す。
+	* 旧グループが存在しない場合は `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 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, running);
-		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)));
 	}
@@ -569,6 +805,56 @@ var FlumeConfluence = class {
 	ids() {
 		return [...this.running.keys()];
 	}
+	/**
+	* 1 グループ分の Flume を開いて FlumeRunning を返す。timeoutMs を指定すると AbortSignal を
+	* ctx.signal として各 source へ注入し、超過時に abort して進行中の connect ごと中止する
+	* (source 側は base クラスが signal を購読して stop() を発火する)。
+	* 失敗時の rollback は 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,
+			deps: this.props.deps,
+			reconnect: this.props.reconnect,
+			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.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) => {
+			return onEvent({
+				...item,
+				groupId: id
+			});
+		};
+	}
 };
 //#endregion
 export { Flume, FlumeClosed, FlumeConfluence, FlumeConnectionError, FlumeHttpError, FlumeParseError, FlumeRunning, FlumeSource, FlumeStartError, createFlumeDefaultDeps };