@spine-event-engine/deployment 2.0.0-snapshot.23 → 2.0.0-snapshot.25

package/dist/internal/backend-membership-kernel.js

@@ -11,10 +11,16 @@
  * or implied. See the License for the specific language governing permissions and limitations under
  * the License.
  */
+var _a;
 const childCleanupTimeoutMs = 1_000;
 /**
  * Manages ephemeral backend membership and its native subscription children.
- * Logical-definition persistence intentionally remains with callers.
+ * Logical-definition persistence remains with callers.
+ *
+ * @typeParam Member A discovered backend member.
+ * @typeParam Request The forwarded unary request.
+ * @typeParam Child The native child subscription handle.
+ * @typeParam Update The native child update.
  */
 export class BackendMembershipKernel {
     #options;
@@ -78,26 +84,15 @@ export class BackendMembershipKernel {
             throw new Error("subscription ID is required");
         if (signal.aborted || this.#closed || this.#nodes.length === 0)
             throw new Error("backend membership is unavailable.");
-        if (!this.#definitions.has(key))
-            this.#definitions.set(key, {
-                definition: definition.slice(),
-                maxChildBytes,
-                children: new Map(),
-                starts: new Set(),
-                active: false,
-                activationController: undefined,
-                updates: undefined,
-                failure: undefined,
-            });
-        const state = this.#definitions.get(key);
-        if (state === undefined)
-            throw new Error("subscription creation was cancelled");
+        const required = new Set(this.#nodes.map((member) => this.#options.memberKey(member)));
+        const state = this.#retainDefinition(key, definition, maxChildBytes);
         await this.#schedule(this.#nodes, false);
         // Re-evaluate cancellation after reconciliation can yield to close().
         // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
         if (signal.aborted || this.#isClosed() || !this.#definitions.has(key))
             throw new Error("subscription creation was cancelled");
-        if (state.failure !== undefined || state.children.size !== this.#members.size) {
+        if (state.failure !== undefined ||
+            [...required].some((memberKey) => !state.children.has(memberKey))) {
             await this.#removeDefinition(key, new AbortController().signal);
             throw state.failure ?? new Error("backend membership is unavailable.");
         }
@@ -117,8 +112,24 @@ export class BackendMembershipKernel {
         const key = this.#options.definitionKey(definition);
         if (key === undefined || key.length === 0)
             throw new Error("subscription ID is required");
-        if (!this.#definitions.has(key))
-            this.#definitions.set(key, {
+        this.#retainDefinition(key, definition, maxChildBytes);
+        await this.#schedule(this.#nodes, false);
+        const failure = this.#definitions.get(key)?.failure;
+        if (failure !== undefined)
+            throw failure;
+    }
+    /**
+     * Retains one logical definition and its child lifecycle state.
+     *
+     * @param key The logical subscription identifier.
+     * @param definition The public subscription definition.
+     * @param maxChildBytes The maximum native child envelope size.
+     * @returns The retained definition state.
+     */
+    #retainDefinition(key, definition, maxChildBytes) {
+        let state = this.#definitions.get(key);
+        if (state === undefined) {
+            state = {
                 definition: definition.slice(),
                 maxChildBytes,
                 children: new Map(),
@@ -127,19 +138,21 @@ export class BackendMembershipKernel {
                 activationController: undefined,
                 updates: undefined,
                 failure: undefined,
-            });
-        await this.#schedule(this.#nodes, false);
-        const failure = this.#definitions.get(key)?.failure;
-        if (failure !== undefined)
-            throw failure;
+                readiness: undefined,
+                lifetime: undefined,
+            };
+            this.#definitions.set(key, state);
+        }
+        return state;
     }
     /**
-     * Creates update relay for a retained logical definition until cancellation.
+     * Activates a retained logical definition until cancellation or terminal child failure.
      *
      * @param definition Supplies the retained logical definition.
      * @param updates Receives relayed child updates.
      * @param signal Cancels update relay.
-     * @returns Completion after cancellation.
+     * @returns Normal completion after cancellation; rejects with a current child failure, possibly
+     * wrapped with a bounded cleanup failure.
      */
     async activate(definition, updates, signal) {
         const key = this.#options.definitionKey(definition);
@@ -149,38 +162,184 @@ export class BackendMembershipKernel {
         if (state.activationController !== undefined)
             throw new Error("subscription activation is already active");
         const controller = new AbortController();
-        state.activationController = controller;
-        state.active = true;
-        state.updates = updates;
+        const { readiness, lifetime } = this.#beginActivation(state, updates, controller);
         const abort = () => {
-            controller.abort();
-            for (const start of state.starts)
-                start.abort();
-            for (const child of state.children.values())
-                child.activationController?.abort();
+            this.#abortActivation(state, readiness, controller);
         };
         if (signal.aborted) {
             abort();
-            state.activationController = undefined;
-            state.active = false;
+            this.#finishActivation(state, controller);
             return;
         }
         signal.addEventListener("abort", abort, { once: true });
         try {
-            await this.#schedule(this.#nodes, false);
-            await Promise.race([
-                BackendMembershipKernel.waitForAbort(signal),
-                BackendMembershipKernel.waitForAbort(controller.signal),
-            ]);
+            await this.#waitActivation(state, readiness, lifetime, signal, controller);
+        }
+        catch (error) {
+            await this.#failActivation(definition, readiness, signal, error);
         }
         finally {
             signal.removeEventListener("abort", abort);
-            if (state.activationController === controller) {
-                state.activationController = undefined;
-                state.active = false;
-                state.updates = undefined;
+            this.#finishActivation(state, controller);
+        }
+    }
+    /**
+     * Captures one logical activation before any child relay starts.
+     * @param state The retained logical definition.
+     * @param updates Receives relayed child updates.
+     * @param controller Cancels this activation.
+     * @returns The readiness and terminal-failure gates for this activation.
+     */
+    #beginActivation(state, updates, controller) {
+        state.activationController = controller;
+        state.active = true;
+        state.updates = updates;
+        const readiness = this.#newReadiness();
+        state.readiness = readiness;
+        const lifetime = this.#newLifetime();
+        state.lifetime = lifetime;
+        return { readiness, lifetime };
+    }
+    /**
+     * Clears a logical relay only when its activation generation is still current.
+     *
+     * @param state The retained definition.
+     * @param controller The completed activation controller.
+     */
+    #finishActivation(state, controller) {
+        if (state.activationController !== controller)
+            return;
+        state.activationController = undefined;
+        state.active = false;
+        state.updates = undefined;
+        state.readiness = undefined;
+        state.lifetime = undefined;
+    }
+    /**
+     * Creates the acknowledgement gate for a strict child activation.
+     *
+     * @returns The gate, or undefined for a generic non-subscription kernel.
+     */
+    #newReadiness() {
+        if (this.#options.isActivationAck === undefined)
+            return undefined;
+        const readiness = {
+            gate: Promise.withResolvers(),
+            seen: new Set(),
+            expected: undefined,
+            first: undefined,
+            emitting: false,
+            reconciling: false,
+            settled: false,
+            failure: undefined,
+        };
+        // spine-log-boundary: deployment.membership_readiness_rejection_observer
+        void readiness.gate.promise.catch(() => undefined);
+        return readiness;
+    }
+    /**
+     * Creates an observed terminal signal for one logical activation.
+     * @returns The unsettled activation lifetime.
+     */
+    #newLifetime() {
+        const lifetime = {
+            gate: Promise.withResolvers(),
+            failure: undefined,
+        };
+        // spine-log-boundary: deployment.membership_lifetime_rejection_observer
+        void lifetime.gate.promise.catch(() => undefined);
+        return lifetime;
+    }
+    /**
+     * Cancels a logical activation and every child attempt.
+     *
+     * @param state The retained definition.
+     * @param readiness Its acknowledgement gate when configured.
+     * @param controller The logical activation controller.
+     */
+    #abortActivation(state, readiness, controller) {
+        controller.abort();
+        if (readiness !== undefined && !readiness.settled) {
+            readiness.settled = true;
+            readiness.gate.resolve(undefined);
+        }
+        for (const start of state.starts)
+            start.abort();
+        for (const child of state.children.values())
+            child.activationController?.abort();
+    }
+    /**
+     * Waits for the required child acknowledgements and later cancellation.
+     *
+     * @param state The retained definition.
+     * @param readiness Its acknowledgement gate when configured.
+     * @param signal The public stream cancellation signal.
+     * @param controller The logical activation controller.
+     * @returns Completion after activation cancellation or readiness failure.
+     */
+    async #waitActivation(state, readiness, lifetime, signal, controller) {
+        await Promise.race([
+            this.#schedule(this.#nodes, false),
+            _a.waitForAbort(signal),
+            _a.waitForAbort(controller.signal),
+            lifetime.gate.promise,
+        ]);
+        this.#throwLifetimeFailure(lifetime);
+        if (signal.aborted || controller.signal.aborted)
+            return;
+        if (readiness !== undefined)
+            await Promise.race([this.#awaitReadiness(state, readiness, signal), lifetime.gate.promise]);
+        this.#throwLifetimeFailure(lifetime);
+        await Promise.race([
+            _a.waitForAbort(signal),
+            _a.waitForAbort(controller.signal),
+            lifetime.gate.promise,
+        ]);
+        this.#throwLifetimeFailure(lifetime);
+    }
+    /**
+     * Preserves a child failure when cancellation and failure settle together.
+     * @param lifetime The current logical activation lifetime.
+     */
+    #throwLifetimeFailure(lifetime) {
+        if (lifetime.failure !== undefined)
+            throw lifetime.failure;
+    }
+    /**
+     * Removes failed strict activation state while preserving the original cause.
+     *
+     * @param definition The logical subscription definition.
+     * @param readiness Its acknowledgement gate when configured.
+     * @param signal The public stream cancellation signal.
+     * @param error The activation failure.
+     */
+    async #failActivation(definition, readiness, signal, error) {
+        // The signal can abort while scheduling or waiting for child readiness.
+        if (!signal.aborted) {
+            try {
+                await this.cancel(definition, new AbortController().signal);
+            }
+            catch (cleanupError) {
+                throw new AggregateError([error, cleanupError], "Child activation cleanup failed.");
             }
         }
+        throw error;
+    }
+    /**
+     * Sets the activation's required child snapshot and waits for its single logical ACK.
+     *
+     * @param state The active logical definition.
+     * @param readiness The current activation's child acknowledgements.
+     * @param signal The public stream cancellation signal.
+     */
+    async #awaitReadiness(state, readiness, signal) {
+        if (state.failure !== undefined)
+            throw state.failure;
+        readiness.expected = new Set(this.#nodes.map((member) => this.#options.memberKey(member)));
+        if (!readiness.reconciling && [...readiness.expected].some((key) => !state.children.has(key)))
+            throw new Error("backend membership is unavailable.");
+        this.#emitReady(state, readiness);
+        await Promise.race([readiness.gate.promise, _a.waitForAbort(signal)]);
     }
     /**
      * Clears one logical definition and its live child subscriptions.
@@ -245,9 +404,12 @@ export class BackendMembershipKernel {
         this.#nodes = [...members];
         this.#pending = { members: this.#nodes, generation: ++this.#generation };
         if (abortStarts)
-            for (const state of this.#definitions.values())
+            for (const state of this.#definitions.values()) {
+                if (state.readiness !== undefined && !state.readiness.settled)
+                    state.readiness.reconciling = true;
                 for (const start of state.starts)
                     start.abort();
+            }
         if (this.#running === undefined) {
             this.#completion = new Promise((resolve) => {
                 this.#complete = resolve;
@@ -257,22 +419,48 @@ export class BackendMembershipKernel {
         return this.#completion;
     }
     async #run() {
+        let finalFailure;
         while (this.#pending !== undefined && !this.#closed) {
             const pending = this.#pending;
             this.#pending = undefined;
             try {
                 await this.#replace(pending.members, pending.generation);
+                finalFailure = undefined;
             }
             catch (error) {
                 // spine-log-boundary: deployment.membership_reconciliation
-                void error;
+                finalFailure = error;
                 /* a later snapshot can recover */
             }
         }
         this.#running = undefined;
+        this.#finishReadinessReconcile(finalFailure);
         this.#complete?.();
         this.#complete = undefined;
     }
+    /**
+     * Releases pending ACK barriers only after the final desired member snapshot is installed.
+     *
+     * @param failure The final reconciliation failure, when one occurred.
+     */
+    #finishReadinessReconcile(failure) {
+        const required = new Set(this.#nodes.map((member) => this.#options.memberKey(member)));
+        for (const state of this.#definitions.values()) {
+            const readiness = state.readiness;
+            if (readiness === undefined || !readiness.reconciling || readiness.settled)
+                continue;
+            readiness.reconciling = false;
+            if (failure !== undefined ||
+                state.failure !== undefined ||
+                required.size === 0 ||
+                [...required].some((key) => !state.children.has(key))) {
+                this.#failReadiness(readiness, failure ?? state.failure ?? new Error("backend membership is unavailable."));
+                continue;
+            }
+            readiness.expected = new Set(required);
+            this.#emitReady(state, readiness);
+        }
+    }
     async #replace(members, generation) {
         if (generation !== this.#generation || this.#closed)
             return;
@@ -343,10 +531,16 @@ export class BackendMembershipKernel {
             this.#members.set(key, { member, client, incarnation: ++this.#incarnation, eligible: false });
     }
     async #syncDefinition(state, generation) {
+        if (state.lifetime?.failure !== undefined)
+            return;
         state.failure = undefined;
         for (const [key, child] of state.children)
             if (!this.#members.has(key)) {
                 state.children.delete(key);
+                state.readiness?.expected?.delete(key);
+                state.readiness?.seen.delete(key);
+                if (state.readiness !== undefined)
+                    this.#emitReady(state, state.readiness);
                 child.controller.abort();
                 child.activationController?.abort();
                 // spine-log-boundary: deployment.membership_child_completion
@@ -374,7 +568,7 @@ export class BackendMembershipKernel {
             }
     }
     async #startChild(state, key, current, generation) {
-        if (this.#closed || generation !== this.#generation)
+        if (this.#closed || generation !== this.#generation || state.lifetime?.failure !== undefined)
             return;
         const controller = new AbortController();
         state.starts.add(controller);
@@ -387,12 +581,29 @@ export class BackendMembershipKernel {
             state.starts.delete(controller);
             this.#childStarts.delete(controller);
         }
+        await this.#installChild(state, key, current, generation, controller, child);
+    }
+    /**
+     * Installs a created child only while its definition and member remain current.
+     *
+     * @param state The retained logical definition.
+     * @param key The backend member identifier.
+     * @param current The member that created the child.
+     * @param generation The reconciliation generation.
+     * @param controller The child creation controller.
+     * @param child The created native child.
+     * @returns Completion after installation or compensation.
+     */
+    async #installChild(state, key, current, generation, controller, child) {
         if (this.#options.childSize(child) > state.maxChildBytes) {
             await this.#compensateChild(current.client, child, controller.signal);
             throw new Error("backend-envelope-too-large");
         }
         if (generation !== this.#generation ||
             this.#members.get(key)?.incarnation !== current.incarnation ||
+            controller.signal.aborted ||
+            this.#definitions.get(this.#options.definitionKey(state.definition) ?? "") !== state ||
+            state.lifetime?.failure !== undefined ||
             this.#isClosed()) {
             await this.#compensateChild(current.client, child, controller.signal);
             return;
@@ -409,33 +620,235 @@ export class BackendMembershipKernel {
             this.#activateChild(state, key, stored, current.client);
     }
     #activateChild(state, key, child, client) {
-        if (child.active || state.updates === undefined)
+        if (child.active || state.updates === undefined || state.lifetime?.failure !== undefined)
             return;
         child.active = true;
         const controller = new AbortController();
         child.activationController = controller;
+        const readiness = state.readiness;
+        const lifetime = state.lifetime;
+        if (readiness !== undefined && !readiness.emitting && !readiness.settled)
+            readiness.expected?.add(key);
+        const logical = state.activationController;
+        const sink = state.updates;
+        const onUpdate = (update) => this.#relayChild(state, key, readiness, logical, sink, update);
+        const activation = { state, key, child, client, controller, logical, lifetime, readiness };
+        this.#observeChildActivation(activation, onUpdate);
+    }
+    /**
+     * Observes one captured child relay through failure and completion.
+     * @param activation The captured child identity and cancellation state.
+     * @param onUpdate Receives child updates for the logical relay.
+     */
+    #observeChildActivation(activation, onUpdate) {
+        const { child, client, controller } = activation;
         // spine-log-boundary: deployment.membership_child_activation
         child.activation = client
-            .activate(child.child, state.updates, controller.signal)
-            .catch(() => undefined)
+            .activate(child.child, onUpdate, controller.signal)
+            .catch((error) => {
+            this.#failChildActivation(activation, error);
+        })
             .then(() => {
-            if (child.activationController !== controller)
-                return;
-            child.activationController = undefined;
-            child.active = false;
-            if (controller.signal.aborted &&
-                state.children.get(key) === child &&
-                state.active &&
-                state.activationController !== undefined &&
-                !state.activationController.signal.aborted &&
-                state.updates !== undefined) {
-                this.#activateChild(state, key, child, client);
+            this.#finishChildActivation(activation);
+        });
+    }
+    /**
+     * Fences the current logical relay when one required child fails or ends.
+     * @param activation The captured child identity and cancellation state.
+     * @param error The child failure or unexpected stream-end cause.
+     */
+    #failChildActivation(activation, error) {
+        const { state, key, child, controller, logical, lifetime, readiness } = activation;
+        if (lifetime === undefined ||
+            logical === undefined ||
+            lifetime.failure !== undefined ||
+            controller.signal.aborted ||
+            logical.signal.aborted ||
+            this.#closed ||
+            state.lifetime !== lifetime ||
+            state.activationController !== logical ||
+            state.children.get(key) !== child ||
+            child.activationController !== controller)
+            return;
+        lifetime.failure =
+            error instanceof Error ? error : new Error("Backend child failed.", { cause: error });
+        for (const start of state.starts)
+            start.abort();
+        for (const current of state.children.values())
+            current.activationController?.abort();
+        lifetime.gate.reject(lifetime.failure);
+        if (readiness !== undefined)
+            this.#failReadiness(readiness, error);
+    }
+    /**
+     * Restarts a cancelled child relay or disposes a child whose stream ended.
+     *
+     * @param activation The captured child identity and cancellation state.
+     */
+    #finishChildActivation(activation) {
+        const { state, key, child, client, controller, lifetime, readiness } = activation;
+        if (child.activationController !== controller)
+            return;
+        if (!controller.signal.aborted) {
+            const failure = new Error("Backend child stream ended unexpectedly.");
+            this.#failChildActivation(activation, failure);
+        }
+        child.activationController = undefined;
+        child.active = false;
+        if (controller.signal.aborted &&
+            lifetime?.failure === undefined &&
+            state.children.get(key) === child &&
+            state.active &&
+            state.activationController !== undefined &&
+            !state.activationController.signal.aborted &&
+            state.updates !== undefined) {
+            this.#activateChild(state, key, child, client);
+            return;
+        }
+        this.#dropEndedChild(state, key, child, client, controller, readiness);
+    }
+    /**
+     * Disposes an ended child only while its logical relay still expects updates.
+     *
+     * @param state The retained logical definition.
+     * @param key The backend member identifier.
+     * @param child The ended child state.
+     * @param client The member client that created the child.
+     * @param controller The child activation controller.
+     * @param readiness The current logical acknowledgement gate.
+     */
+    #dropEndedChild(state, key, child, client, controller, readiness) {
+        if (state.children.get(key) !== child ||
+            controller.signal.aborted ||
+            !state.active ||
+            state.activationController === undefined ||
+            state.activationController.signal.aborted ||
+            readiness?.failure !== undefined)
+            return;
+        state.children.delete(key);
+        readiness?.seen.delete(key);
+        void this.#disposeEndedChild(client, child.child);
+    }
+    /**
+     * Tracks cleanup of a child whose stream ended independently of logical cancellation.
+     *
+     * @param client The member client that created the child.
+     * @param child The ended child subscription.
+     */
+    async #disposeEndedChild(client, child) {
+        const running = this.#compensateChild(client, child, new AbortController().signal);
+        const cleanups = this.#childCleanup.get(client) ?? new Set();
+        const tracked = running.then(() => undefined);
+        cleanups.add(tracked);
+        this.#childCleanup.set(client, cleanups);
+        try {
+            await tracked;
+        }
+        finally {
+            cleanups.delete(tracked);
+            if (cleanups.size === 0)
+                this.#childCleanup.delete(client);
+        }
+    }
+    /**
+     * Consumes one child's ACK locally and gates its business updates behind logical readiness.
+     *
+     * @param state The retained logical definition.
+     * @param key The child member key.
+     * @param readiness The readiness state captured when this child started.
+     * @param logical The logical activation controller captured when this child started.
+     * @param sink The original logical update sink captured when this child started.
+     * @param update The child update to inspect or forward.
+     */
+    async #relayChild(state, key, readiness, logical, sink, update) {
+        if (logical === undefined || !this.#relayIsCurrent(state, logical))
+            return;
+        if (readiness === undefined) {
+            await sink(update);
+            return;
+        }
+        if (state.readiness !== readiness || state.activationController !== logical)
+            return;
+        const isAck = this.#options.isActivationAck?.(update) ?? false;
+        if (!readiness.seen.has(key)) {
+            if (!isAck)
+                throw new Error("Backend child activation ACK is missing or invalid.");
+            readiness.seen.add(key);
+            readiness.first ??= update;
+            this.#emitReady(state, readiness);
+            return;
+        }
+        if (isAck)
+            throw new Error("Backend child sent a duplicate activation ACK.");
+        await readiness.gate.promise;
+        if (state.readiness === readiness && this.#relayIsCurrent(state, logical))
+            await state.updates?.(update);
+    }
+    /**
+     * Checks generation, cancellation, and terminal failure before a child update.
+     * @param state The retained logical definition.
+     * @param logical The child relay's captured activation controller.
+     * @returns Whether the captured activation still accepts updates.
+     */
+    #relayIsCurrent(state, logical) {
+        return (state.activationController === logical &&
+            !logical.signal.aborted &&
+            state.lifetime?.failure === undefined);
+    }
+    /**
+     * Forwards exactly one logical ACK after every required child has acknowledged attachment.
+     *
+     * @param state The retained logical definition.
+     * @param readiness The current activation's child acknowledgement state.
+     */
+    #emitReady(state, readiness) {
+        if (readiness.reconciling ||
+            readiness.emitting ||
+            readiness.settled ||
+            readiness.expected === undefined ||
+            readiness.expected.size === 0 ||
+            ![...readiness.expected].every((key) => readiness.seen.has(key)))
+            return;
+        const update = readiness.first;
+        const sink = state.updates;
+        if (update === undefined || sink === undefined) {
+            this.#failReadiness(readiness, new Error("Backend child activation ACK is unavailable."));
+            return;
+        }
+        readiness.emitting = true;
+        let logicalAck;
+        try {
+            logicalAck = this.#options.logicalActivationAck?.(state.definition, update) ?? update;
+        }
+        catch (error) {
+            this.#failReadiness(readiness, error);
+            return;
+        }
+        void sink(logicalAck).then(() => {
+            if (readiness.settled)
                 return;
-            }
-            if (state.children.get(key) === child && !controller.signal.aborted)
-                state.children.delete(key);
+            readiness.settled = true;
+            readiness.gate.resolve(undefined);
+        }, (error) => {
+            this.#failReadiness(readiness, error);
         });
     }
+    /**
+     * Rejects pending readiness once while retaining the original child or sink failure.
+     *
+     * @param readiness The current activation's child acknowledgement state.
+     * @param error The failing child or update-sink cause.
+     */
+    #failReadiness(readiness, error) {
+        if (readiness.settled)
+            return;
+        readiness.settled = true;
+        readiness.failure =
+            error instanceof Error
+                ? error
+                : new Error("Backend child activation failed.", { cause: error });
+        readiness.gate.reject(readiness.failure);
+    }
     async #removeDefinition(key, signal) {
         const state = this.#definitions.get(key);
         if (state === undefined)
@@ -457,6 +870,10 @@ export class BackendMembershipKernel {
             if (child === undefined)
                 continue;
             state.children.delete(key);
+            state.readiness?.expected?.delete(key);
+            state.readiness?.seen.delete(key);
+            if (state.readiness !== undefined)
+                this.#emitReady(state, state.readiness);
             try {
                 await this.#cleanupChild(child, client);
             }
@@ -521,8 +938,6 @@ export class BackendMembershipKernel {
                 continue;
     }
     async #disposeChild(pending, signal) {
-        if (pending.running !== undefined)
-            return false;
         const controller = new AbortController();
         const abort = () => {
             controller.abort();
@@ -531,15 +946,35 @@ export class BackendMembershipKernel {
         if (signal.aborted)
             abort();
         try {
-            let timer;
-            const timeout = new Promise((_resolve, reject) => {
-                timer = setTimeout(() => {
-                    reject(new Error("backend child cleanup timed out"));
-                }, childCleanupTimeoutMs);
-                timer.unref();
-            });
-            try {
-                const running = pending.client.dispose(pending.child, controller.signal);
+            await this.#awaitChildDisposal(pending, controller);
+            return true;
+        }
+        catch {
+            controller.abort();
+            return false;
+        }
+        finally {
+            signal.removeEventListener("abort", abort);
+        }
+    }
+    /**
+     * Races one shared child disposal against its existing bounded wait.
+     *
+     * @param pending The retained child disposal attempt.
+     * @param controller Cancels the entered disposal when its wait fails.
+     * @returns Completion when the child disposal settles within its limit.
+     */
+    async #awaitChildDisposal(pending, controller) {
+        let timer;
+        const timeout = new Promise((_resolve, reject) => {
+            timer = setTimeout(() => {
+                reject(new Error("backend child cleanup timed out"));
+            }, childCleanupTimeoutMs);
+            timer.unref();
+        });
+        try {
+            const running = pending.running ?? pending.client.dispose(pending.child, controller.signal);
+            if (pending.running === undefined) {
                 pending.running = running;
                 const settled = () => {
                     if (pending.running === running)
@@ -547,20 +982,12 @@ export class BackendMembershipKernel {
                 };
                 // spine-log-boundary: deployment.membership_child_cleanup_retry
                 void running.then(settled, settled);
-                await Promise.race([running, timeout]);
             }
-            finally {
-                if (timer !== undefined)
-                    clearTimeout(timer);
-            }
-            return true;
-        }
-        catch {
-            controller.abort();
-            return false;
+            await Promise.race([running, timeout]);
         }
         finally {
-            signal.removeEventListener("abort", abort);
+            if (timer !== undefined)
+                clearTimeout(timer);
         }
     }
     #retainFailedChildCleanup(client, child) {
@@ -601,6 +1028,7 @@ export class BackendMembershipKernel {
                 start.abort();
         await this.#running;
         await Promise.allSettled([...this.#definitions.keys()].map((key) => this.#removeDefinition(key, new AbortController().signal)));
+        await Promise.allSettled([...this.#childCleanup.values()].flatMap((pending) => [...pending]));
         await this.#retryChildCleanup();
         await Promise.all([...this.#members.values()].map(({ client }) => this.#dispose(client)));
         this.#members.clear();
@@ -611,4 +1039,5 @@ export class BackendMembershipKernel {
             throw new Error("backend child cleanup remains incomplete.");
     }
 }
+_a = BackendMembershipKernel;
 //# sourceMappingURL=backend-membership-kernel.js.map