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

package/dist/server/environment-attachment.js

@@ -1,2062 +0,0 @@
-/*
- * Copyright 2026, CodeMatters. All rights reserved.
- *
- * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except
- * in compliance with the License. You may obtain a copy of the License at
- *
- * https://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing, software distributed under the License
- * is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express
- * or implied. See the License for the specific language governing permissions and limitations under
- * the License.
- */
-import { clone } from "@bufbuild/protobuf";
-import { TenantIdSchema } from "@spine-event-engine/proto";
-import {} from "@spine-event-engine/storage";
-import { TenantBoundary } from "@spine-event-engine/storage/provider";
-import { DeliveryRunCoordinator, } from "../delivery/delivery-run-coordinator.js";
-import { ParkedDeliveryObligations, } from "../delivery/parked-delivery-obligations.js";
-import { ShardIndex } from "../delivery/shard-index.js";
-import { EnvironmentDeliveryWorker, } from "./environment-delivery-worker.js";
-import { EnvironmentDeliveryRecords } from "./environment-delivery-records.js";
-class AttachedEnvironmentRegistration {
-    startup;
-    token;
-    #binding;
-    #records;
-    constructor(claim, binding, startup, records) {
-        this.token = claim.token;
-        this.#binding = binding;
-        this.startup = startup;
-        this.#records = records;
-        Object.freeze(this);
-    }
-    get generation() {
-        return this.#binding.generation;
-    }
-    records() {
-        return this.#records();
-    }
-}
-/**
- * Tracks registration ownership and generations for one server environment.
- *
- * @internal
- */
-export class EnvironmentRegistrations {
-    #claims = new Map();
-    #generation;
-    #ownership;
-    #nextToken = 0;
-    /**
-     * Returns the number of active claims.
-     *
-     * @returns The active claim count.
-     */
-    get count() {
-        return this.#claims.size;
-    }
-    /**
-     * Returns the active generation, if any.
-     *
-     * @returns The current generation or `undefined`.
-     */
-    get generation() {
-        return this.#generation;
-    }
-    /**
-     * Sets the current generation during a safe handoff.
-     *
-     * @param generation Supplies the replacement generation.
-     * @returns The retired generation.
-     */
-    replace(generation) {
-        if (this.#generation === undefined) {
-            throw new Error("Environment generation is not current.");
-        }
-        const previous = this.#generation;
-        this.#generation = generation;
-        return previous;
-    }
-    /**
-     * Creates a registration claim in the current generation.
-     *
-     * @param ownership Selects caller or server ownership.
-     * @returns The new opaque registration claim.
-     */
-    claim(ownership) {
-        if (this.#ownership !== undefined && this.#ownership !== ownership) {
-            throw new Error("Server-owned environment registration requires exclusive ownership.");
-        }
-        this.#generation ??= Object.freeze({ generation: true });
-        this.#ownership ??= ownership;
-        this.#nextToken += 1;
-        const claim = Object.freeze({
-            token: `registration-${this.#nextToken.toString()}`,
-            generation: this.#generation,
-        });
-        this.#claims.set(claim.token, claim);
-        return claim;
-    }
-    /**
-     * Removes one failed attachment without disturbing sibling claims.
-     *
-     * @internal
-     * @param token Identifies the claim.
-     * @returns The remaining claim count.
-     */
-    remove(token) {
-        if (!this.#claims.delete(token)) {
-            throw new Error("Environment registration is not active.");
-        }
-        return this.#claims.size;
-    }
-    /**
-     * Clears an empty generation after its retirement is safe.
-     *
-     * @internal
-     * @param generation Identifies the generation to clear.
-     */
-    clear(generation) {
-        if (this.#claims.size > 0) {
-            throw new Error("Environment generation still has live registrations.");
-        }
-        if (this.#generation !== generation) {
-            throw new Error("Environment generation is not current.");
-        }
-        this.#generation = undefined;
-        this.#ownership = undefined;
-    }
-}
-/**
- * Coordinates generation attachment, detachment, recovery, and retirement for one environment.
- *
- * @internal
- */
-export class EnvironmentAttachments {
-    #registrations = new EnvironmentRegistrations();
-    #generations = new Map();
-    #createWorker;
-    #logger;
-    #deliveryPorts;
-    #report;
-    #transitionFaults;
-    #handles = new WeakMap();
-    #attached = new Map();
-    #nonLastDetachTokens = new Set();
-    #serial = Promise.resolve();
-    #failedRollback;
-    #failedLastDetach;
-    #stop;
-    #permanentCloseAdmission;
-    #permanentlyClosed = false;
-    /**
-     * Creates an attachment owner.
-     * @param options Optionally supplies lifecycle test seams.
-     */
-    constructor(options = {}) {
-        this.#createWorker = options.createWorker ?? (() => new EnvironmentDeliveryWorker());
-        this.#logger = options.logger;
-        this.#deliveryPorts = options.deliveryPorts ?? (() => undefined);
-        this.#report = options.report ?? (() => Promise.resolve());
-        this.#transitionFaults = options.transitionFaults;
-    }
-    /**
-     * Returns the number of bounded unresolved diagnostics.
-     *
-     * @internal
-     * @returns The unresolved count.
-     */
-    get unresolvedReportedDomainCount() {
-        let count = 0;
-        for (const generation of this.#generations.values()) {
-            count += generation.unresolvedReportedDomainCount;
-        }
-        return count;
-    }
-    /**
-     * Returns the number of live registrations.
-     *
-     * @internal
-     * @returns The active registration count.
-     */
-    get activeRegistrationCount() {
-        return this.#registrations.count;
-    }
-    /**
-     * Returns the number of configured delivery owners.
-     *
-     * @internal
-     * @returns The configured owner count.
-     */
-    get configuredOwnerCount() {
-        let count = 0;
-        for (const generation of this.#generations.values()) {
-            count += generation.configuredOwnerCount;
-        }
-        return count;
-    }
-    /**
-     * Returns the number of configured delivery scopes.
-     *
-     * @internal
-     * @returns The configured scope count.
-     */
-    get configuredScopeCount() {
-        let count = 0;
-        for (const generation of this.#generations.values()) {
-            count += generation.configuredScopeCount;
-        }
-        return count;
-    }
-    /**
-     * Checks whether a failed attachment owns unfinished rollback.
-     *
-     * @internal
-     * @returns Whether rollback remains.
-     */
-    get failedStartPending() {
-        return this.#failedRollback !== undefined;
-    }
-    /**
-     * Checks whether a rejection owns failed-start rollback retry.
-     *
-     * @internal
-     * @param error Supplies the rejection.
-     * @returns Whether retry is required.
-     */
-    failedStartRetryPending(error) {
-        const rollback = this.#failedRollback;
-        return rollback?.rejection !== undefined && rollback.rejection === error;
-    }
-    /**
-     * Checks whether detachment made an endpoint safe.
-     *
-     * @internal
-     * @param attachment Identifies the attachment.
-     * @returns Whether the endpoint is safe.
-     */
-    endpointSafe(attachment) {
-        const attached = this.#handles.get(attachment);
-        if (attached === undefined) {
-            throw new Error("Environment attachment handle is not owned by this environment.");
-        }
-        if (attached.detachKind === "last") {
-            return attached.generation.replacementSafe;
-        }
-        if (attached.detachKind === "non-last") {
-            return attached.generation.registrationEndpointSafe(attached.claim.token);
-        }
-        return false;
-    }
-    /**
-     * Checks whether an attachment owns rejected detach work.
-     *
-     * @internal
-     * @param attachment Identifies the attachment.
-     * @returns Whether detach retry is pending.
-     */
-    detachRetryPending(attachment) {
-        const attached = this.#handles.get(attachment);
-        if (attached === undefined) {
-            throw new Error("Environment attachment handle is not owned by this environment.");
-        }
-        return attached.operation?.status === "rejected";
-    }
-    /**
-     * Attaches configured descriptors to an environment generation.
-     *
-     * @param options Supplies ownership and descriptors.
-     * @returns The successful attachment handle.
-     */
-    attach(options) {
-        if (this.#permanentlyClosed) {
-            return Promise.reject(EnvironmentAttachmentAssembly.environmentClosedError());
-        }
-        const gate = Promise.withResolvers();
-        const stop = this.#stop;
-        const waitForStop = stop !== undefined && !stop.completed;
-        const snapshotDescriptors = !waitForStop && this.#permanentCloseAdmission === undefined;
-        const waiter = {
-            options: Object.freeze({
-                ownership: options.ownership,
-                descriptors: snapshotDescriptors
-                    ? Object.freeze([...options.descriptors])
-                    : options.descriptors,
-            }),
-            gate,
-            snapshotDescriptors,
-            status: waitForStop ? "waiting" : "queued",
-        };
-        if (waitForStop) {
-            stop.waiters.push(waiter);
-        }
-        else {
-            this.#queueAttachment(waiter);
-        }
-        return gate.promise;
-    }
-    #queueAttachment(waiter) {
-        waiter.status = "queued";
-        const attaching = this.#serial.then(async () => {
-            if (this.#permanentlyClosed) {
-                throw EnvironmentAttachmentAssembly.environmentClosedError();
-            }
-            const admittedOptions = Object.freeze({
-                ownership: waiter.options.ownership,
-                descriptors: waiter.snapshotDescriptors
-                    ? waiter.options.descriptors
-                    : Object.freeze([...waiter.options.descriptors]),
-            });
-            const attachment = await this.#startQueuedAttachment(admittedOptions);
-            waiter.status = "complete";
-            waiter.gate.resolve(attachment);
-        });
-        // spine-log-boundary: server.attachment_queue_serial_tail
-        this.#serial = attaching.then(() => undefined, () => undefined);
-        // spine-log-boundary: server.attachment_queued_gate
-        void attaching.catch((error) => {
-            waiter.status = "complete";
-            waiter.gate.reject(error);
-        });
-    }
-    async #releaseStopWaiters(stop) {
-        if (!stop.waitersReleased) {
-            stop.waitersReleased = true;
-            const settlements = stop.waiters.map((waiter) => {
-                this.#queueAttachment(waiter);
-                return waiter.gate.promise;
-            });
-            stop.waiters.length = 0;
-            stop.waiterSettlement = Promise.allSettled(settlements).then(() => undefined);
-        }
-        await stop.waiterSettlement;
-    }
-    async #startQueuedAttachment(options) {
-        if (this.#permanentlyClosed) {
-            throw EnvironmentAttachmentAssembly.environmentClosedError();
-        }
-        if (this.#failedRollback !== undefined) {
-            throw EnvironmentAttachmentValues.explicitRetryError();
-        }
-        if (this.#failedLastDetach !== undefined) {
-            throw EnvironmentAttachmentValues.detachRetryRequiredError();
-        }
-        const claim = this.#registrations.claim(options.ownership);
-        let generation = this.#generations.get(claim.generation);
-        if (generation === undefined) {
-            try {
-                generation = new DeliveryGeneration(this.#createWorker(), this.#report, this.#deliveryPorts(), this.#logger);
-            }
-            catch (error) {
-                if (this.#registrations.remove(claim.token) === 0) {
-                    this.#registrations.clear(claim.generation);
-                }
-                throw error;
-            }
-            this.#generations.set(claim.generation, generation);
-        }
-        const binding = { generation: claim.generation };
-        const attachment = await this.#attachRegistration(generation, claim, options.descriptors, binding);
-        this.#handles.set(attachment, {
-            claim,
-            generation,
-            binding,
-            descriptors: options.descriptors,
-            operation: undefined,
-            claimRemoved: false,
-            detachKind: undefined,
-            generationCleared: false,
-        });
-        const handle = this.#handles.get(attachment);
-        if (handle === undefined) {
-            throw new Error("Attached environment handle was not retained.");
-        }
-        this.#attached.set(claim.token, handle);
-        return attachment;
-    }
-    /**
-     * Stops delivery work while preserving a retryable failed stop.
-     *
-     * @returns A promise that settles after delivery work stops.
-     */
-    stopDelivery() {
-        if (this.#permanentlyClosed) {
-            return Promise.reject(EnvironmentAttachmentAssembly.environmentClosedError());
-        }
-        const current = this.#stop;
-        if (current !== undefined) {
-            if (current.status === "rejected") {
-                return Promise.reject(EnvironmentAttachmentValues.deliveryStopRetryError());
-            }
-            return current.promise;
-        }
-        const stop = {
-            admitted: false,
-            generation: undefined,
-            old: undefined,
-            survivors: undefined,
-            routes: undefined,
-            oldRetired: false,
-            oldRetirement: { status: "pending" },
-            candidateGeneration: undefined,
-            candidate: undefined,
-            routeUnits: undefined,
-            routeSnapshots: undefined,
-            routePrepared: 0,
-            scopes: new TransitionScopes(),
-            published: false,
-            reopened: undefined,
-            drained: false,
-            waiters: [],
-            waitersReleased: false,
-            waiterSettlement: undefined,
-            completed: false,
-            cancelledByClose: undefined,
-            promise: Promise.resolve(),
-            status: "running",
-            retrying: false,
-        };
-        this.#stop = stop;
-        return this.#queueStop(stop, false);
-    }
-    #queueStop(stop, retrying) {
-        stop.status = "running";
-        stop.retrying = retrying;
-        const gate = Promise.withResolvers();
-        stop.promise = gate.promise;
-        const admission = this.#serial.then(() => {
-            void this.#continueStop(stop).then(() => {
-                gate.resolve(undefined);
-            }, (reason) => {
-                gate.reject(reason);
-            });
-        });
-        // spine-log-boundary: server.attachment_stop_serial_tail
-        this.#serial = admission.then(() => undefined, () => undefined);
-        // spine-log-boundary: server.attachment_stop_admission_gate
-        void admission.catch(gate.reject);
-        void stop.promise.then(() => {
-            stop.status = "complete";
-            if (this.#stop === stop) {
-                this.#stop = undefined;
-            }
-        }, () => {
-            if (stop.completed) {
-                stop.status = "complete";
-                if (this.#stop === stop) {
-                    this.#stop = undefined;
-                }
-            }
-            else {
-                stop.status = "rejected";
-            }
-        });
-        return stop.promise;
-    }
-    /**
-     * Retries a previously rejected delivery stop.
-     *
-     * @returns A promise that settles after the stop retry completes.
-     */
-    retryDeliveryStop() {
-        if (this.#permanentlyClosed) {
-            return Promise.reject(EnvironmentAttachmentAssembly.environmentClosedError());
-        }
-        const stop = this.#stop;
-        if (stop?.status === "running" && stop.retrying) {
-            return stop.promise;
-        }
-        if (stop?.status !== "rejected") {
-            return Promise.reject(new Error("Environment has no failed delivery stop to retry."));
-        }
-        return this.#queueStop(stop, true);
-    }
-    async #continueStop(stop) {
-        if (stop.cancelledByClose !== undefined) {
-            stop.completed = true;
-            await stop.waiterSettlement;
-            throw stop.cancelledByClose;
-        }
-        if (!stop.admitted) {
-            if (this.#failedRollback !== undefined) {
-                await this.#refuseStop(stop, EnvironmentAttachmentValues.explicitRetryError());
-            }
-            if (this.#failedLastDetach !== undefined) {
-                await this.#refuseStop(stop, EnvironmentAttachmentValues.detachRetryRequiredError());
-            }
-            if (this.#failedNonLastDetachOwnsRegistration()) {
-                await this.#refuseStop(stop, EnvironmentAttachmentValues.detachRetryRequiredError());
-            }
-            const generation = this.#registrations.generation;
-            if (generation === undefined) {
-                stop.completed = true;
-                await this.#releaseStopWaiters(stop);
-                return;
-            }
-            const old = this.#generations.get(generation);
-            if (old === undefined) {
-                await this.#refuseStop(stop, new Error("Environment generation is not current."));
-            }
-            stop.generation = generation;
-            stop.old = old;
-            stop.survivors = Object.freeze([...this.#attached.values()]);
-            stop.admitted = true;
-        }
-        const { old, survivors } = stop;
-        if (old === undefined || survivors === undefined) {
-            throw new Error("Admitted delivery stop is missing generation state.");
-        }
-        if (stop.routes === undefined) {
-            stop.routes = Object.freeze(survivors.map((survivor) => old.closeRegistration(survivor.claim.token, (descriptor, ready) => {
-                stop.scopes.buffer(survivor.claim.token, descriptor, ready);
-            })));
-            old.captureTransition(stop.scopes);
-        }
-        if (!stop.oldRetired) {
-            const retirement = await old.retire();
-            if (retirement.status === "failed") {
-                if (!old.replacementSafe) {
-                    throw retirement.reason;
-                }
-                stop.oldRetirement = {
-                    status: "retained",
-                    reason: retirement.reason,
-                    causes: retirement.causes,
-                };
-            }
-            stop.oldRetired = true;
-        }
-        try {
-            let routeUnits = stop.routeUnits;
-            if (routeUnits === undefined) {
-                const routes = stop.routes;
-                routeUnits = Object.freeze(survivors.flatMap((survivor, registration) => {
-                    const readiness = routes.at(registration);
-                    if (readiness === undefined) {
-                        throw new Error("Closed delivery route is missing readiness.");
-                    }
-                    return survivor.descriptors.map((descriptor) => ({
-                        survivor,
-                        descriptor,
-                        readiness,
-                    }));
-                }));
-                stop.routeUnits = routeUnits;
-            }
-            if (stop.routeSnapshots === undefined) {
-                const snapshots = [];
-                for (const route of routeUnits) {
-                    snapshots.push(await EnvironmentAttachmentAssembly.snapshotDescriptor(route.descriptor));
-                }
-                stop.routeSnapshots = Object.freeze(snapshots);
-            }
-            if (stop.candidate === undefined) {
-                const candidate = new DeliveryGeneration(this.#createWorker(), this.#report, this.#deliveryPorts(), this.#logger);
-                stop.candidateGeneration = Object.freeze({ generation: true });
-                stop.candidate = candidate;
-            }
-            const candidate = stop.candidate;
-            const candidateGeneration = stop.candidateGeneration;
-            if (candidateGeneration === undefined) {
-                throw new Error("Candidate delivery generation was not retained.");
-            }
-            while (stop.routePrepared < routeUnits.length) {
-                const route = routeUnits[stop.routePrepared];
-                const snapshot = stop.routeSnapshots[stop.routePrepared];
-                if (route === undefined || snapshot === undefined) {
-                    throw new Error("Prepared delivery route is missing its snapshot.");
-                }
-                this.#transitionFaults?.onRoutePrepare?.(route.descriptor);
-                const scopes = await candidate.prepareTransferredRoute(Object.freeze({ token: route.survivor.claim.token, generation: candidateGeneration }), snapshot, route.readiness);
-                stop.scopes.capture(route.survivor.claim.token, route.descriptor, scopes, "startup");
-                stop.routePrepared += 1;
-            }
-            let transfer = stop.scopes.nextPending();
-            while (transfer !== undefined) {
-                const version = stop.scopes.begin(transfer);
-                const settling = candidate.recoverTransferred(transfer.token, transfer.descriptor, transfer.ready);
-                let fault = { status: "none" };
-                try {
-                    this.#transitionFaults?.onScopeTransfer?.(transfer.descriptor, stop.scopes.sources(transfer));
-                }
-                catch (error) {
-                    fault = { status: "retained", reason: error };
-                }
-                const failures = [];
-                try {
-                    await settling;
-                }
-                catch (error) {
-                    failures.push(error);
-                }
-                if (fault.status === "retained") {
-                    failures.push(fault.reason);
-                }
-                if (failures.length > 0) {
-                    stop.scopes.reject(transfer);
-                    EnvironmentAttachmentValues.throwCurrentAggregation(failures);
-                }
-                stop.scopes.complete(transfer, version);
-                transfer = stop.scopes.nextPending();
-            }
-            if (!stop.published) {
-                const generation = stop.generation;
-                if (generation === undefined) {
-                    throw new Error("Admitted delivery stop is missing its generation.");
-                }
-                this.#generations.delete(generation);
-                this.#generations.set(candidateGeneration, candidate);
-                this.#registrations.replace(candidateGeneration);
-                for (const survivor of survivors) {
-                    survivor.generation = candidate;
-                    survivor.binding.generation = candidateGeneration;
-                }
-                stop.published = true;
-            }
-            if (stop.reopened === undefined) {
-                const reopened = [];
-                for (const survivor of survivors) {
-                    reopened.push(...candidate.openRegistration(survivor.claim.token));
-                }
-                stop.reopened = Object.freeze(reopened);
-            }
-            if (!stop.drained) {
-                await candidate.recoverReopened(stop.reopened);
-                stop.drained = true;
-            }
-        }
-        catch (error) {
-            const failures = [
-                ...this.#takeOldRetirementCauses(stop),
-                ...EnvironmentAttachmentValues.currentAggregationCauses(error),
-            ];
-            EnvironmentAttachmentValues.throwFailures(failures, "Environment delivery stop transition failed.");
-        }
-        stop.completed = true;
-        await this.#releaseStopWaiters(stop);
-        if (stop.oldRetirement.status === "retained") {
-            const { reason } = stop.oldRetirement;
-            stop.oldRetirement = { status: "emitted" };
-            throw reason;
-        }
-    }
-    #takeOldRetirementCauses(stop) {
-        if (stop.oldRetirement.status !== "retained") {
-            return Object.freeze([]);
-        }
-        const { causes } = stop.oldRetirement;
-        stop.oldRetirement = { status: "emitted" };
-        return causes;
-    }
-    async #refuseStop(stop, error) {
-        stop.completed = true;
-        await this.#releaseStopWaiters(stop);
-        throw error;
-    }
-    /**
-     * Accepts permanent close after all active registrations retire.
-     *
-     * @internal
-     * @returns A promise that resolves after permanent close is admitted.
-     */
-    admitPermanentClose() {
-        if (this.#permanentlyClosed) {
-            return Promise.resolve();
-        }
-        const current = this.#permanentCloseAdmission;
-        if (current !== undefined) {
-            return current;
-        }
-        const admission = this.#serial.then(() => {
-            if (this.#registrations.count !== 0) {
-                throw new Error("ServerEnvironment cannot close while it is in use.");
-            }
-            if (this.#failedRollback !== undefined) {
-                throw EnvironmentAttachmentValues.explicitRetryError();
-            }
-            this.#cancelProvisionalStop();
-            if (this.#registrations.generation !== undefined || this.#generations.size !== 0) {
-                throw new Error("Environment generation is not current.");
-            }
-            this.#permanentlyClosed = true;
-        });
-        this.#permanentCloseAdmission = admission;
-        // spine-log-boundary: server.attachment_permanent_close_serial_tail
-        this.#serial = admission.then(() => undefined, () => undefined);
-        const clearAdmission = () => {
-            if (this.#permanentCloseAdmission === admission) {
-                this.#permanentCloseAdmission = undefined;
-            }
-        };
-        void admission.then(clearAdmission, clearAdmission);
-        return admission;
-    }
-    #cancelProvisionalStop() {
-        const stop = this.#stop;
-        if (stop === undefined || stop.admitted || stop.completed) {
-            return;
-        }
-        const error = EnvironmentAttachmentAssembly.environmentClosedError();
-        stop.cancelledByClose = error;
-        stop.waitersReleased = true;
-        const waiters = [...stop.waiters];
-        stop.waiters.length = 0;
-        stop.waiterSettlement = Promise.allSettled(waiters.map((waiter) => waiter.gate.promise)).then(() => undefined);
-        for (const waiter of waiters) {
-            waiter.status = "complete";
-            waiter.gate.reject(error);
-        }
-        if (this.#stop === stop) {
-            this.#stop = undefined;
-        }
-    }
-    /**
-     * Removes one attached registration.
-     *
-     * @param attachment Identifies the attachment to detach.
-     * @returns A promise that settles after the attachment detaches.
-     */
-    detach(attachment) {
-        const attached = this.#handles.get(attachment);
-        if (attached === undefined) {
-            return Promise.reject(new Error("Environment attachment handle is not owned by this environment."));
-        }
-        if (attached.operation !== undefined) {
-            return attached.operation.promise;
-        }
-        if (this.#rejectedStopOwns(attached)) {
-            return Promise.reject(EnvironmentAttachmentValues.deliveryStopRetryError());
-        }
-        if (this.#failedRollback !== undefined) {
-            return Promise.reject(EnvironmentAttachmentValues.explicitRetryError());
-        }
-        return this.#queueDetach(attached);
-    }
-    /**
-     * Retries rejected detachment for one attachment.
-     *
-     * @param attachment Identifies the attachment to retry.
-     * @returns A promise that settles after the detach retry completes.
-     */
-    retryDetach(attachment) {
-        const attached = this.#handles.get(attachment);
-        if (attached === undefined) {
-            return Promise.reject(new Error("Environment attachment handle is not owned by this environment."));
-        }
-        if (this.#rejectedStopOwns(attached)) {
-            return Promise.reject(EnvironmentAttachmentValues.deliveryStopRetryError());
-        }
-        const operation = attached.operation;
-        if (operation === undefined) {
-            return Promise.reject(new Error("Environment attachment has no failed detach to retry."));
-        }
-        if (operation.status === "running") {
-            return Promise.reject(new Error("Environment attachment detach has not rejected."));
-        }
-        if (operation.status === "complete" ||
-            !attached.generation.hasRegistration(attached.claim.token)) {
-            operation.status = "complete";
-            return Promise.resolve();
-        }
-        if (this.#failedRollback !== undefined) {
-            return Promise.reject(EnvironmentAttachmentValues.explicitRetryError());
-        }
-        return this.#queueDetach(attached, operation);
-    }
-    #queueDetach(attached, previousOperation) {
-        const detaching = this.#serial.then(() => {
-            if (this.#incompleteStopOwns(attached)) {
-                throw EnvironmentAttachmentValues.deliveryStopRetryError();
-            }
-            if (this.#failedRollback !== undefined) {
-                attached.operation = previousOperation;
-                throw EnvironmentAttachmentValues.explicitRetryError();
-            }
-            return this.#detachRegistration(attached);
-        });
-        const operation = { promise: detaching, status: "running" };
-        attached.operation = operation;
-        // spine-log-boundary: server.attachment_detach_serial_tail
-        this.#serial = detaching.then(() => undefined, () => undefined);
-        void detaching.then(() => {
-            operation.status = "complete";
-        }, () => {
-            operation.status = "rejected";
-        });
-        return detaching;
-    }
-    #failedNonLastDetachOwnsRegistration() {
-        for (const attached of this.#attached.values()) {
-            if (attached.detachKind === "non-last" &&
-                attached.operation?.status !== "complete" &&
-                attached.generation.hasRegistration(attached.claim.token)) {
-                return true;
-            }
-        }
-        return false;
-    }
-    #rejectedStopOwns(attached) {
-        const stop = this.#stop;
-        return (stop?.status === "rejected" && stop.admitted && stop.survivors?.includes(attached) === true);
-    }
-    #incompleteStopOwns(attached) {
-        const stop = this.#stop;
-        return stop?.admitted === true && !stop.drained && stop.survivors?.includes(attached) === true;
-    }
-    async #detachRegistration(attached) {
-        if (attached.detachKind === undefined) {
-            const liveRegistrations = this.#registrations.count - this.#nonLastDetachTokens.size;
-            if (this.#registrations.count === 1) {
-                attached.detachKind = "last";
-            }
-            else if (liveRegistrations <= 1) {
-                throw new Error("Environment attachment cannot detach the reserved live registration.");
-            }
-            else {
-                attached.detachKind = "non-last";
-                this.#nonLastDetachTokens.add(attached.claim.token);
-            }
-        }
-        if (attached.detachKind === "last") {
-            try {
-                await attached.generation.retireRegistration(attached.claim.token);
-            }
-            catch (error) {
-                if (!attached.generation.replacementSafe) {
-                    this.#failedLastDetach = attached;
-                }
-                throw error;
-            }
-            finally {
-                if (attached.generation.replacementSafe) {
-                    this.#clearRetiredGeneration(attached);
-                }
-            }
-            return;
-        }
-        try {
-            await attached.generation.detachRegistration(attached.claim.token);
-        }
-        finally {
-            if (!attached.generation.hasRegistration(attached.claim.token) && !attached.claimRemoved) {
-                this.#registrations.remove(attached.claim.token);
-                this.#attached.delete(attached.claim.token);
-                this.#nonLastDetachTokens.delete(attached.claim.token);
-                attached.claimRemoved = true;
-            }
-        }
-    }
-    #clearRetiredGeneration(attached) {
-        if (!attached.claimRemoved) {
-            this.#registrations.remove(attached.claim.token);
-            attached.claimRemoved = true;
-        }
-        if (!attached.generationCleared) {
-            this.#generations.delete(attached.binding.generation);
-            this.#registrations.clear(attached.binding.generation);
-            this.#attached.delete(attached.claim.token);
-            attached.generationCleared = true;
-        }
-        if (this.#failedLastDetach === attached) {
-            this.#failedLastDetach = undefined;
-        }
-    }
-    /**
-     * Retries rollback following a rejected attachment start.
-     *
-     * @returns A promise that settles after failed-start rollback retries.
-     */
-    retryFailedStart() {
-        const rollback = this.#failedRollback;
-        if (rollback === undefined) {
-            return Promise.reject(new Error("Environment has no failed-start rollback to retry."));
-        }
-        if (rollback.retry !== undefined) {
-            return rollback.retry;
-        }
-        const retry = this.#serial.then(() => {
-            if (this.#registrations.count === 0) {
-                rollback.mode = "generation";
-            }
-            return this.#continueRollback(rollback);
-        });
-        rollback.retry = retry;
-        // spine-log-boundary: server.attachment_rollback_serial_tail
-        this.#serial = retry.then(() => undefined, () => undefined);
-        // spine-log-boundary: server.attachment_rollback_retry_reset
-        void retry.catch(() => {
-            if (this.#failedRollback === rollback) {
-                rollback.retry = undefined;
-            }
-        });
-        return retry;
-    }
-    async #attachRegistration(generation, claim, descriptors, binding) {
-        try {
-            return await generation.attach(claim, descriptors, false, binding);
-        }
-        catch (startError) {
-            const remaining = this.#registrations.remove(claim.token);
-            const rollback = {
-                claim,
-                generation,
-                mode: remaining === 0 ? "generation" : "registration",
-                inFlight: undefined,
-                retry: undefined,
-                rejection: undefined,
-            };
-            this.#failedRollback = rollback;
-            try {
-                await this.#continueRollback(rollback);
-            }
-            catch (rollbackError) {
-                const rejection = EnvironmentAttachmentValues.failedStartError(startError, rollbackError);
-                rollback.rejection = rejection;
-                throw rejection;
-            }
-            throw startError;
-        }
-    }
-    #continueRollback(rollback) {
-        if (rollback.inFlight !== undefined) {
-            return rollback.inFlight;
-        }
-        const gate = Promise.withResolvers();
-        rollback.inFlight = gate.promise;
-        void this.#performRollback(rollback).then(() => {
-            this.#completeRollback(rollback);
-            gate.resolve(undefined);
-        }, (error) => {
-            if (this.#rollbackSafe(rollback)) {
-                this.#completeRollback(rollback);
-            }
-            else {
-                rollback.inFlight = undefined;
-            }
-            gate.reject(error);
-        });
-        return gate.promise;
-    }
-    async #performRollback(rollback) {
-        if (rollback.mode === "generation") {
-            await rollback.generation.retireFailedRegistration(rollback.claim.token);
-        }
-        else {
-            await rollback.generation.rollbackRegistration(rollback.claim.token);
-        }
-    }
-    #rollbackSafe(rollback) {
-        return rollback.mode === "generation"
-            ? rollback.generation.replacementSafe
-            : !rollback.generation.hasRegistration(rollback.claim.token);
-    }
-    #completeRollback(rollback) {
-        if (rollback.mode === "generation") {
-            this.#generations.delete(rollback.claim.generation);
-            this.#registrations.clear(rollback.claim.generation);
-        }
-        this.#failedRollback = undefined;
-    }
-}
-class TransitionScopes {
-    #registrations = new Map();
-    #pendingHead;
-    #pendingTail;
-    capture(token, descriptor, scopes, source) {
-        for (const scope of scopes) {
-            this.#record(token, descriptor, scope.ready, source, false);
-        }
-    }
-    buffer(token, descriptor, ready) {
-        this.#record(token, descriptor, ready, "buffered", true);
-    }
-    nextPending() {
-        return this.#pendingHead;
-    }
-    begin(unit) {
-        if (this.#pendingHead !== unit ||
-            !unit.queued ||
-            unit.inFlightVersion !== undefined ||
-            unit.transferredVersion >= unit.version) {
-            throw new Error("Environment transition scope is not pending.");
-        }
-        this.#pendingHead = unit.pendingNext;
-        if (this.#pendingHead === undefined) {
-            this.#pendingTail = undefined;
-        }
-        unit.queued = false;
-        unit.pendingNext = undefined;
-        unit.inFlightVersion = unit.version;
-        unit.dirtyDuringFlight = false;
-        return unit.inFlightVersion;
-    }
-    complete(unit, version) {
-        if (unit.inFlightVersion !== version) {
-            throw new Error("Environment transition scope checkpoint is not current.");
-        }
-        unit.transferredVersion = version;
-        unit.inFlightVersion = undefined;
-        unit.dirtyDuringFlight = false;
-        if (unit.transferredVersion < unit.version) {
-            this.#enqueue(unit);
-        }
-    }
-    reject(unit) {
-        unit.inFlightVersion = undefined;
-        unit.dirtyDuringFlight = false;
-        this.#enqueue(unit, true);
-    }
-    sources(unit) {
-        return Object.freeze(transitionSourceOrder.filter((source) => unit.provenance.has(source)));
-    }
-    #record(token, descriptor, ready, source, dirty) {
-        const descriptors = this.#registrations.get(token) ??
-            new Map();
-        const scopes = descriptors.get(descriptor) ?? new Map();
-        let unit = scopes.get(EnvironmentAttachmentValues.readyKey(ready));
-        if (unit === undefined) {
-            unit = {
-                token,
-                descriptor,
-                ready,
-                provenance: new Set(),
-                version: 1,
-                transferredVersion: 0,
-                inFlightVersion: undefined,
-                dirtyDuringFlight: false,
-                queued: false,
-                pendingNext: undefined,
-            };
-            scopes.set(EnvironmentAttachmentValues.readyKey(ready), unit);
-            descriptors.set(descriptor, scopes);
-            this.#registrations.set(token, descriptors);
-            this.#enqueue(unit);
-        }
-        else if (dirty) {
-            if (unit.inFlightVersion !== undefined && !unit.dirtyDuringFlight) {
-                unit.version += 1;
-                unit.dirtyDuringFlight = true;
-            }
-            else if (unit.inFlightVersion === undefined && unit.transferredVersion === unit.version) {
-                unit.version += 1;
-                this.#enqueue(unit);
-            }
-        }
-        unit.provenance.add(source);
-    }
-    #enqueue(unit, first = false) {
-        if (unit.queued) {
-            return;
-        }
-        unit.queued = true;
-        if (first) {
-            unit.pendingNext = this.#pendingHead;
-            this.#pendingHead = unit;
-            this.#pendingTail ??= unit;
-        }
-        else if (this.#pendingTail === undefined) {
-            unit.pendingNext = undefined;
-            this.#pendingHead = unit;
-            this.#pendingTail = unit;
-        }
-        else {
-            unit.pendingNext = undefined;
-            this.#pendingTail.pendingNext = unit;
-            this.#pendingTail = unit;
-        }
-    }
-}
-const transitionSourceOrder = Object.freeze([
-    "configured",
-    "startup",
-    "buffered",
-    "retained",
-]);
-class RegistrationOwnership {
-    #scopes = new Map();
-    #ownerKeys = new Set();
-    add(runtime) {
-        this.#ownerKeys.add(runtime.owner.key);
-        for (const scope of runtime.scopes) {
-            this.#scopes.set(EnvironmentAttachmentValues.scopeKey(scope), scope);
-        }
-    }
-    get scopes() {
-        return Object.freeze([...this.#scopes.values()]);
-    }
-    get ownerKeys() {
-        return Object.freeze([...this.#ownerKeys]);
-    }
-}
-class DeliveryGeneration {
-    #worker;
-    /**
-     * Environment logger child retained for later runtime containment owners.
-     */
-    logger;
-    #ports;
-    #report;
-    #descriptors = new WeakSet();
-    #runtimes = new WeakMap();
-    #deliveryRecords = new EnvironmentDeliveryRecords();
-    #registrations = new Map();
-    #reportedFailures = new ReportedFailures();
-    #overlapDomains = new Map();
-    #configuredOwners = new Set();
-    #factoryIds = new WeakMap();
-    #nextFactory = 0;
-    #coordinator;
-    #nextOwner = 0;
-    #retiredWithoutCoordinator = false;
-    constructor(worker, report, ports, logger) {
-        this.#worker = worker;
-        this.#report = report;
-        this.#ports = ports;
-        this.logger = logger;
-    }
-    get replacementSafe() {
-        return this.#coordinator?.replacementSafe ?? this.#retiredWithoutCoordinator;
-    }
-    get unresolvedReportedDomainCount() {
-        return this.#reportedFailures.size;
-    }
-    get configuredOwnerCount() {
-        return this.#configuredOwners.size;
-    }
-    get configuredScopeCount() {
-        return this.#coordinator?.configuredScopeCount ?? 0;
-    }
-    hasRegistration(token) {
-        return this.#registrations.has(token);
-    }
-    registrationEndpointSafe(token) {
-        const state = this.#registrations.get(token);
-        return state === undefined || (state.detach?.quiescent === true && state.detach.barrier);
-    }
-    async attach(claim, descriptors, transferred = false, binding = { generation: claim.generation }, transferredReadiness) {
-        this.#requireFresh(descriptors);
-        const registration = await EnvironmentAttachmentAssembly.assembleRegistration(descriptors, (descriptor, tenant, context, endpoints, storageFactory) => this.#runtimeFromSnapshot(descriptor, tenant, context, endpoints, storageFactory));
-        const ownership = new RegistrationOwnership();
-        for (const runtime of registration.runtimes) {
-            this.#addRuntime(runtime);
-            ownership.add(runtime);
-        }
-        this.#deliveryRecords.register(claim.token, ownership.scopes);
-        const readiness = transferredReadiness ?? this.#readiness(registration, ownership, claim.token);
-        if (transferredReadiness !== undefined) {
-            readiness.rebind((descriptor, ready) => this.#prepareReady(descriptor, ready, ownership, claim.token), (scope) => {
-                this.#notify(scope);
-            });
-        }
-        this.#registrations.set(claim.token, {
-            readiness,
-            startupScopes: registration.scopes,
-            ownership,
-            descriptors,
-            scopeDescriptors: EnvironmentAttachmentAssembly.registrationScopeDescriptors(registration),
-        });
-        if (!transferred) {
-            await this.#transition(registration, readiness);
-        }
-        return await this.#recover(claim, binding, transferred ? registration.scopes : readiness.open(registration.scopes));
-    }
-    prepareTransferredRoute(claim, snapshot, readiness) {
-        const descriptor = snapshot.descriptor;
-        this.#validateFreshDescriptors([descriptor]);
-        const registration = EnvironmentAttachmentAssembly.assembleRegistrationSnapshots([snapshot], (candidate, tenant, context, endpoints, storageFactory) => this.#runtimeFromSnapshot(candidate, tenant, context, endpoints, storageFactory));
-        let state = this.#registrations.get(claim.token);
-        if (state === undefined) {
-            state = {
-                readiness,
-                startupScopes: Object.freeze([]),
-                ownership: new RegistrationOwnership(),
-                descriptors: Object.freeze([]),
-                scopeDescriptors: new Map(),
-            };
-            this.#registrations.set(claim.token, state);
-        }
-        for (const runtime of registration.runtimes) {
-            this.#addRuntime(runtime);
-            state.ownership.add(runtime);
-        }
-        this.#deliveryRecords.register(claim.token, registration.scopes);
-        for (const scope of registration.scopes) {
-            state.scopeDescriptors.set(EnvironmentAttachmentValues.scopeKey(scope), descriptor);
-        }
-        state.startupScopes = EnvironmentAttachmentValues.appendScopes(state.startupScopes, registration.scopes);
-        state.descriptors = Object.freeze([...state.descriptors, descriptor]);
-        const ownership = state.ownership;
-        readiness.rebindDescriptor(descriptor, (candidate, ready) => this.#prepareReady(candidate, ready, ownership, claim.token), (scope) => {
-            this.#notify(scope);
-        });
-        this.#descriptors.add(descriptor);
-        return Promise.resolve(registration.scopes);
-    }
-    async recoverTransferred(token, descriptor, ready) {
-        const state = this.#registrations.get(token);
-        if (state === undefined) {
-            throw new Error("Environment registration is not active.");
-        }
-        const scope = this.#prepareReady(descriptor, ready, state.ownership, token);
-        const domains = [this.#overlapDomain(scope)];
-        const previouslyBlocked = this.#reportedFailures.overlaps(domains);
-        const settlement = await this.#start([scope]);
-        this.#reportedFailures.resolve(this.#resolvedDomains([scope], settlement));
-        const blocked = previouslyBlocked && this.#reportedFailures.overlaps(domains);
-        EnvironmentAttachmentAssembly.throwRejected(this.#deliveryRecords.registrationRecords(token), blocked);
-    }
-    async rollbackRegistration(token) {
-        const state = this.#registrations.get(token);
-        if (state === undefined) {
-            return;
-        }
-        state.readiness.fail();
-        const ownerKeys = state.ownership.ownerKeys;
-        const scopes = state.ownership.scopes;
-        const rollback = (state.rollback ??= { stopped: false, quiescent: false });
-        if (!rollback.stopped) {
-            this.#worker.stopOwners(ownerKeys);
-            rollback.stopped = true;
-        }
-        if (!rollback.quiescent) {
-            await this.#worker.awaitOwnersSettled(ownerKeys);
-            rollback.quiescent = true;
-        }
-        const failures = [];
-        try {
-            await this.#consumeRegistration(token, false);
-        }
-        catch (error) {
-            failures.push(error);
-        }
-        try {
-            await this.#worker.retireOwners(ownerKeys);
-        }
-        catch (error) {
-            failures.push(error);
-        }
-        let reclaimed = false;
-        try {
-            await this.#coordinator?.removeOwners(ownerKeys);
-            reclaimed = true;
-        }
-        catch (error) {
-            failures.push(error);
-        }
-        if (reclaimed) {
-            for (const ownerKey of ownerKeys) {
-                this.#configuredOwners.delete(ownerKey);
-            }
-            this.#forgetScopes(scopes);
-        }
-        this.#registrations.delete(token);
-        EnvironmentAttachmentValues.throwFailures(failures, "Environment registration rollback failed.");
-    }
-    async detachRegistration(token) {
-        const state = this.#registrations.get(token);
-        if (state === undefined) {
-            return;
-        }
-        state.readiness.fail();
-        const ownerKeys = state.ownership.ownerKeys;
-        const scopes = state.ownership.scopes;
-        const detach = (state.detach ??= {
-            stopped: false,
-            quiescent: false,
-            barrier: false,
-            recordsConsumed: false,
-            causes: Object.freeze([]),
-            reportAttempted: false,
-            workerRetirementAttempted: false,
-            coordinatorRemoved: false,
-        });
-        if (!detach.stopped) {
-            this.#worker.stopOwners(ownerKeys);
-            detach.stopped = true;
-        }
-        if (!detach.quiescent) {
-            await this.#worker.awaitOwnersSettled(ownerKeys);
-            detach.quiescent = true;
-        }
-        if (!detach.barrier) {
-            await this.#coordinator?.awaitOwnersBarrier(ownerKeys);
-            detach.barrier = true;
-        }
-        const failures = [];
-        if (!detach.recordsConsumed) {
-            try {
-                detach.causes = this.#deliveryRecords.detach(token);
-                detach.recordsConsumed = true;
-            }
-            catch (error) {
-                failures.push(error);
-            }
-        }
-        if (detach.recordsConsumed && !detach.reportAttempted) {
-            detach.reportAttempted = true;
-            try {
-                if (detach.causes.length > 0) {
-                    await this.#report(detach.causes);
-                }
-            }
-            catch (error) {
-                failures.push(error);
-            }
-        }
-        if (!detach.workerRetirementAttempted) {
-            detach.workerRetirementAttempted = true;
-            try {
-                await this.#worker.retireOwners(ownerKeys);
-            }
-            catch (error) {
-                failures.push(error);
-            }
-        }
-        if (!detach.coordinatorRemoved) {
-            try {
-                if (ownerKeys.length > 0) {
-                    await this.#coordinator?.removeOwners(ownerKeys);
-                }
-                detach.coordinatorRemoved = true;
-            }
-            catch (error) {
-                failures.push(error);
-            }
-        }
-        if (detach.coordinatorRemoved) {
-            for (const ownerKey of ownerKeys) {
-                this.#configuredOwners.delete(ownerKey);
-            }
-            this.#forgetScopes(scopes);
-            for (const descriptor of state.descriptors) {
-                this.#descriptors.delete(descriptor);
-                this.#runtimes.delete(descriptor);
-            }
-            this.#registrations.delete(token);
-        }
-        EnvironmentAttachmentValues.throwFailures(failures, "Environment registration detach failed.");
-    }
-    async retireRegistration(token) {
-        this.#registrations.get(token)?.readiness.fail();
-        if (this.#coordinator === undefined) {
-            try {
-                await this.#consumeRegistration(token, true);
-            }
-            finally {
-                this.#registrations.delete(token);
-                this.#retiredWithoutCoordinator = true;
-                this.#dropRetiredState();
-            }
-            return;
-        }
-        try {
-            await this.#coordinator.retire(async () => {
-                try {
-                    await this.#consumeRegistration(token, true);
-                }
-                finally {
-                    this.#registrations.delete(token);
-                }
-            });
-        }
-        finally {
-            if (this.replacementSafe) {
-                this.#dropRetiredState();
-            }
-        }
-    }
-    async retire() {
-        const token = this.#registrations.keys().next().value;
-        if (token === undefined) {
-            this.#retiredWithoutCoordinator = true;
-            return Object.freeze({ status: "succeeded" });
-        }
-        const coordinator = this.#coordinator;
-        try {
-            if (coordinator === undefined) {
-                await this.#consumeRegistration(token, true);
-                this.#retiredWithoutCoordinator = true;
-            }
-            else {
-                await coordinator.retire(() => this.#consumeRegistration(token, true));
-            }
-        }
-        catch (reason) {
-            return Object.freeze({
-                status: "failed",
-                reason,
-                causes: coordinator?.takeRetirementFailureCauses(reason) ?? Object.freeze([reason]),
-            });
-        }
-        this.#registrations.clear();
-        this.#dropRetiredState();
-        return Object.freeze({ status: "succeeded" });
-    }
-    captureTransition(capture) {
-        const pending = this.#coordinator?.settlement().pending ?? Object.freeze([]);
-        const retained = this.#deliveryRecords.retainedScopeSnapshot(pending);
-        for (const [token, state] of this.#registrations) {
-            this.#captureScopes(token, state, this.#deliveryRecords.configuredScopes(token), "configured", capture);
-            this.#captureScopes(token, state, state.startupScopes, "startup", capture);
-            this.#captureScopes(token, state, retained.get(token) ?? Object.freeze([]), "retained", capture);
-        }
-    }
-    closeRegistration(token, onBuffered) {
-        const state = this.#registrations.get(token);
-        if (state === undefined) {
-            throw new Error("Environment registration is not active.");
-        }
-        state.readiness.prepareTransition(onBuffered);
-        return state.readiness;
-    }
-    openRegistration(token) {
-        const state = this.#registrations.get(token);
-        if (state === undefined) {
-            throw new Error("Environment registration is not active.");
-        }
-        return state.readiness.open([]);
-    }
-    async recoverReopened(scopes) {
-        await this.#start(scopes);
-    }
-    async retireFailedRegistration(token) {
-        await this.retireRegistration(token);
-    }
-    #notify(scope) {
-        if (this.#worker.notify === undefined) {
-            this.#coordinator?.notify(scope);
-            return;
-        }
-        this.#worker.notify(scope);
-    }
-    #readiness(registration, ownership, token) {
-        return new RegistrationReadiness(registration.descriptors, (descriptor, ready) => this.#prepareReady(descriptor, ready, ownership, token), (scope) => {
-            this.#notify(scope);
-        });
-    }
-    async #transition(registration, readiness) {
-        await Promise.all(registration.descriptors.map(({ descriptor, scopes }) => descriptor.transition(scopes.map(({ ready }) => ready), (ready) => {
-            readiness.notify(descriptor, ready);
-        }, {
-            allowEmpty: true,
-            ...(this.#ports === undefined ? {} : { ports: this.#ports }),
-        })));
-    }
-    async #recover(claim, binding, startup) {
-        const domains = startup.map((scope) => this.#overlapDomain(scope));
-        const previouslyBlocked = this.#reportedFailures.overlaps(domains);
-        const settlement = await this.#start(startup);
-        this.#reportedFailures.resolve(this.#resolvedDomains(startup, settlement));
-        const blocked = previouslyBlocked && this.#reportedFailures.overlaps(domains);
-        const startupRecords = this.#deliveryRecords.registrationRecords(claim.token);
-        EnvironmentAttachmentAssembly.throwRejected(startupRecords, blocked);
-        return EnvironmentAttachmentValues.handle(claim, binding, settlement, () => startupRecords);
-    }
-    async #consumeRegistration(token, consumeGeneration) {
-        const state = this.#registrations.get(token);
-        if (state === undefined) {
-            return;
-        }
-        const causes = consumeGeneration
-            ? this.#deliveryRecords.retire()
-            : this.#deliveryRecords.rollback(token);
-        let reportFailure = { status: "none" };
-        try {
-            if (causes.length > 0) {
-                await this.#report(causes);
-            }
-        }
-        catch (error) {
-            reportFailure = { status: "retained", reason: error };
-        }
-        if (!consumeGeneration) {
-            const unresolved = new Set(this.#deliveryRecords
-                .records()
-                .filter(({ hasCause, reportedSinceResolution }) => hasCause && reportedSinceResolution)
-                .flatMap(({ units: recordUnits }) => recordUnits));
-            this.#reportedFailures.record(state.startupScopes.flatMap((scope) => unresolved.has(EnvironmentAttachmentValues.scopeKey(scope))
-                ? [this.#overlapDomain(scope)]
-                : []));
-        }
-        if (reportFailure.status === "retained") {
-            throw reportFailure.reason;
-        }
-    }
-    async #start(startup) {
-        return startup.length === 0 || this.#coordinator === undefined
-            ? EnvironmentAttachmentValues.emptySettlement()
-            : await this.#coordinator.start(startup);
-    }
-    #prepareReady(descriptor, ready, ownership, token) {
-        const tenant = ready.tenantId === undefined
-            ? Object.freeze({})
-            : Object.freeze({ tenantId: ready.tenantId });
-        const runtime = this.#runtime(descriptor, tenant);
-        this.#addRuntime(runtime);
-        ownership.add(runtime);
-        this.#deliveryRecords.register(token, runtime.scopes);
-        const state = this.#registrations.get(token);
-        for (const configured of runtime.scopes) {
-            state?.scopeDescriptors.set(EnvironmentAttachmentValues.scopeKey(configured), descriptor);
-        }
-        const scope = runtime.scopes.find(({ ready: candidate }) => EnvironmentAttachmentValues.readyKey(candidate) ===
-            EnvironmentAttachmentValues.readyKey(ready));
-        if (scope === undefined) {
-            throw new Error("Environment readiness is outside the descriptor endpoint domain.");
-        }
-        return scope;
-    }
-    #captureScopes(token, state, scopes, source, capture) {
-        for (const scope of scopes) {
-            const descriptor = state.scopeDescriptors.get(EnvironmentAttachmentValues.scopeKey(scope));
-            if (descriptor === undefined) {
-                throw new Error("Environment transition scope has no descriptor route.");
-            }
-            capture.capture(token, descriptor, [scope], source);
-        }
-    }
-    #addRuntime(runtime) {
-        if (this.#configuredOwners.has(runtime.owner.key)) {
-            return;
-        }
-        this.#worker.add(runtime);
-        this.#configuredOwners.add(runtime.owner.key);
-        if (this.#coordinator === undefined) {
-            this.#coordinator = new DeliveryRunCoordinator({
-                scopes: runtime.scopes,
-                worker: this.#worker,
-                onSettlement: (settlement) => {
-                    this.#deliveryRecords.observe(settlement);
-                },
-            });
-        }
-        else {
-            this.#coordinator.configure(runtime.scopes);
-        }
-    }
-    #runtime(descriptor, tenant) {
-        const existing = this.#existingRuntime(descriptor, tenant);
-        if (existing !== undefined) {
-            return existing;
-        }
-        return this.#runtimeFromSnapshot(descriptor, tenant, descriptor.storageContext(tenant), descriptor.endpoints(), descriptor.storageFactory);
-    }
-    #runtimeFromSnapshot(descriptor, tenant, context, endpoints, storageFactory) {
-        const existing = this.#existingRuntime(descriptor, tenant);
-        if (existing !== undefined) {
-            return existing;
-        }
-        const tenantKey = EnvironmentAttachmentValues.tenantKey(tenant);
-        this.#nextOwner += 1;
-        const owner = Object.freeze({ key: `environment-owner-${this.#nextOwner.toString()}` });
-        const runtime = Object.freeze({
-            owner,
-            descriptor,
-            storageFactory,
-            tenant,
-            context,
-            ...(this.logger === undefined ? {} : { logger: this.logger }),
-            scopes: Object.freeze(endpoints.map((endpoint) => EnvironmentAttachmentValues.readyScope(owner, endpoint, tenant))),
-        });
-        for (const scope of runtime.scopes) {
-            this.#overlapDomains.set(EnvironmentAttachmentValues.scopeKey(scope), this.#stableDomain(storageFactory, context, scope.ready));
-        }
-        const runtimes = this.#runtimes.get(descriptor) ?? new Map();
-        runtimes.set(tenantKey, runtime);
-        this.#runtimes.set(descriptor, runtimes);
-        return runtime;
-    }
-    #existingRuntime(descriptor, tenant) {
-        return this.#runtimes.get(descriptor)?.get(EnvironmentAttachmentValues.tenantKey(tenant));
-    }
-    #stableDomain(factory, context, ready) {
-        let factoryId = this.#factoryIds.get(factory);
-        if (factoryId === undefined) {
-            this.#nextFactory += 1;
-            factoryId = this.#nextFactory;
-            this.#factoryIds.set(factory, factoryId);
-        }
-        return JSON.stringify([
-            factoryId,
-            context.name,
-            context.multitenant,
-            context.tenantId ?? null,
-            EnvironmentAttachmentValues.readyKey(ready),
-        ]);
-    }
-    #overlapDomain(scope) {
-        const domain = this.#overlapDomains.get(EnvironmentAttachmentValues.scopeKey(scope));
-        if (domain === undefined) {
-            throw new Error("Environment overlap domain is not configured.");
-        }
-        return domain;
-    }
-    #resolvedDomains(startup, settlement) {
-        const current = new Set(startup.map((scope) => EnvironmentAttachmentValues.scopeKey(scope)));
-        return settlement.scopes.flatMap(({ scope, disposition }) => current.has(EnvironmentAttachmentValues.scopeKey(scope)) && disposition !== "REJECTED"
-            ? [this.#overlapDomain(scope)]
-            : []);
-    }
-    #forgetScopes(scopes) {
-        for (const scope of scopes) {
-            this.#overlapDomains.delete(EnvironmentAttachmentValues.scopeKey(scope));
-        }
-    }
-    #dropRetiredState() {
-        this.#reportedFailures.clear();
-        this.#overlapDomains.clear();
-        this.#factoryIds = new WeakMap();
-        this.#nextFactory = 0;
-    }
-    #requireFresh(descriptors) {
-        for (const descriptor of this.#validateFreshDescriptors(descriptors)) {
-            this.#descriptors.add(descriptor);
-        }
-    }
-    #validateFreshDescriptors(descriptors) {
-        const unique = new Set();
-        for (const descriptor of descriptors) {
-            if (unique.has(descriptor)) {
-                throw new Error("Attachment requires unique context delivery descriptors.");
-            }
-            if (this.#descriptors.has(descriptor)) {
-                throw new Error("Context delivery descriptor is already attached.");
-            }
-            unique.add(descriptor);
-        }
-        return unique;
-    }
-}
-/**
- * Buffers descriptor readiness while one attachment transitions between generations.
- *
- * @internal
- */
-export class RegistrationReadiness {
-    #descriptors;
-    #canonical = new WeakMap();
-    #destinations = new WeakMap();
-    #buffered = new Map();
-    #onTransition;
-    #mode = "waiting";
-    #invalid = false;
-    /**
-     * Creates readiness buffering for configured descriptors.
-     *
-     * @param descriptors Supplies descriptors and their initial scopes.
-     * @param onPrepare Converts a readiness notification into a scope.
-     * @param onNotify Delivers an opened scope to its generation.
-     */
-    constructor(descriptors, onPrepare, onNotify) {
-        this.#descriptors = Object.freeze(descriptors.map(({ descriptor }) => descriptor));
-        for (const { descriptor, scopes } of descriptors) {
-            this.#canonical.set(descriptor, new Map(scopes.map((scope) => [EnvironmentAttachmentValues.readyKey(scope.ready), scope])));
-            this.#destinations.set(descriptor, { onPrepare, onNotify });
-        }
-    }
-    /**
-     * Records or forwards one endpoint readiness notification.
-     *
-     * @param descriptor Identifies the reporting descriptor.
-     * @param ready Supplies the ready endpoint.
-     */
-    notify(descriptor, ready) {
-        if (this.#mode === "failed") {
-            return;
-        }
-        if (this.#mode === "open") {
-            try {
-                const destination = this.#destinations.get(descriptor);
-                if (destination === undefined) {
-                    throw new Error("Registration readiness descriptor is not configured.");
-                }
-                const scope = destination.onPrepare(descriptor, ready);
-                destination.onNotify(scope);
-            }
-            catch {
-                this.#mode = "failed";
-            }
-            return;
-        }
-        if (this.#onTransition !== undefined) {
-            try {
-                const snapshot = EnvironmentAttachmentValues.cloneReady(ready);
-                this.#onTransition(descriptor, snapshot);
-                this.#buffer(descriptor, snapshot);
-            }
-            catch {
-                this.#invalid = true;
-            }
-            return;
-        }
-        const scope = this.#canonical.get(descriptor)?.get(EnvironmentAttachmentValues.readyKey(ready));
-        if (scope === undefined) {
-            this.#invalid = true;
-            return;
-        }
-        this.#buffer(descriptor, EnvironmentAttachmentValues.cloneReady(scope.ready));
-    }
-    /**
-     * Clears readiness and discards buffered notifications.
-     */
-    fail() {
-        this.#mode = "failed";
-        this.#buffered.clear();
-        this.#onTransition = undefined;
-    }
-    /**
-     * Prepares notification buffering for a generation transition.
-     *
-     * @param onBuffered Receives notifications buffered during the transition.
-     */
-    prepareTransition(onBuffered) {
-        if (this.#mode !== "open") {
-            throw new Error("Registration readiness is not open.");
-        }
-        this.#onTransition = onBuffered;
-        this.#mode = "waiting";
-    }
-    /**
-     * Updates every descriptor for a replacement generation.
-     *
-     * @param onPrepare Converts readiness into replacement scopes.
-     * @param onNotify Delivers opened replacement scopes.
-     */
-    rebind(onPrepare, onNotify) {
-        for (const descriptor of this.#descriptors) {
-            this.rebindDescriptor(descriptor, onPrepare, onNotify);
-        }
-    }
-    /**
-     * Updates one descriptor for a replacement generation.
-     *
-     * @param descriptor Identifies the descriptor to rebind.
-     * @param onPrepare Converts readiness into replacement scopes.
-     * @param onNotify Delivers opened replacement scopes.
-     */
-    rebindDescriptor(descriptor, onPrepare, onNotify) {
-        if (this.#mode !== "waiting") {
-            throw new Error("Registration readiness is not prepared for transition.");
-        }
-        this.#destinations.set(descriptor, { onPrepare, onNotify });
-    }
-    /**
-     * Opens readiness and returns initial plus buffered scopes.
-     *
-     * @param startup Supplies scopes recovered during startup.
-     * @returns Immutable scopes to run or notify.
-     */
-    open(startup) {
-        if (this.#mode !== "waiting") {
-            throw new Error("Registration readiness can only open once.");
-        }
-        if (this.#invalid) {
-            this.#mode = "failed";
-            this.#buffered.clear();
-            throw new Error("Registration readiness received an unconfigured scope.");
-        }
-        const scopes = new Map();
-        for (const scope of startup) {
-            scopes.set(EnvironmentAttachmentValues.scopeKey(scope), scope);
-        }
-        for (const [descriptor, readies] of this.#buffered) {
-            const destination = this.#destinations.get(descriptor);
-            if (destination === undefined) {
-                throw new Error("Registration readiness descriptor is not configured.");
-            }
-            for (const ready of readies.values()) {
-                const scope = destination.onPrepare(descriptor, ready);
-                scopes.set(EnvironmentAttachmentValues.scopeKey(scope), scope);
-            }
-        }
-        this.#buffered.clear();
-        this.#onTransition = undefined;
-        this.#mode = "open";
-        return Object.freeze([...scopes.values()]);
-    }
-    #buffer(descriptor, ready) {
-        const readies = this.#buffered.get(descriptor) ?? new Map();
-        readies.set(EnvironmentAttachmentValues.readyKey(ready), ready);
-        this.#buffered.set(descriptor, readies);
-    }
-}
-/**
- * Groups immutable registration-assembly operations.
- * @internal
- */
-const EnvironmentAttachmentAssembly = Object.freeze({
-    environmentClosedError() {
-        return new Error("ServerEnvironment is closed.");
-    },
-    async assembleRegistration(descriptors, runtimeFor) {
-        const snapshots = [];
-        for (const descriptor of descriptors) {
-            snapshots.push(await EnvironmentAttachmentAssembly.snapshotDescriptor(descriptor));
-        }
-        return EnvironmentAttachmentAssembly.assembleRegistrationSnapshots(snapshots, runtimeFor);
-    },
-    async snapshotDescriptor(descriptor) {
-        const storageFactory = descriptor.storageFactory;
-        const tenants = await descriptor.startupScopes();
-        const endpoints = Object.freeze(descriptor.endpoints().map((endpoint) => Object.freeze({
-            label: endpoint.label,
-            targetTypeUrl: endpoint.targetTypeUrl,
-            shard: new ShardIndex(endpoint.shard.index, endpoint.shard.ofTotal),
-        })));
-        const startup = tenants.map((tenant) => {
-            const capturedTenant = Object.freeze({
-                ...(tenant.tenantId === undefined
-                    ? {}
-                    : { tenantId: clone(TenantIdSchema, tenant.tenantId) }),
-            });
-            const context = descriptor.storageContext(capturedTenant);
-            return Object.freeze({
-                tenant: capturedTenant,
-                context: context.multitenant
-                    ? Object.freeze({
-                        name: context.name,
-                        multitenant: true,
-                        tenantId: clone(TenantIdSchema, context.tenantId),
-                    })
-                    : Object.freeze({ name: context.name, multitenant: false }),
-            });
-        });
-        return Object.freeze({
-            descriptor,
-            storageFactory,
-            startup: Object.freeze(startup),
-            endpoints,
-        });
-    },
-    assembleRegistrationSnapshots(snapshots, runtimeFor) {
-        const scopes = new Map();
-        const runtimes = [];
-        const assembled = [];
-        for (const { descriptor, storageFactory, startup, endpoints } of snapshots) {
-            const descriptorScopes = [];
-            for (const { tenant, context } of startup) {
-                const runtime = runtimeFor(descriptor, tenant, context, endpoints, storageFactory);
-                const runtimeScopes = runtime.scopes;
-                if (runtimeScopes.length > 0) {
-                    runtimes.push(runtime);
-                }
-                for (const scope of runtimeScopes) {
-                    scopes.set(EnvironmentAttachmentValues.scopeKey(scope), scope);
-                    descriptorScopes.push(scope);
-                }
-            }
-            if (endpoints.length > 0) {
-                assembled.push({ descriptor, scopes: Object.freeze(descriptorScopes) });
-            }
-        }
-        return {
-            scopes: Object.freeze([...scopes.values()]),
-            runtimes: Object.freeze(runtimes),
-            descriptors: Object.freeze(assembled),
-        };
-    },
-    registrationScopeDescriptors(registration) {
-        const descriptors = new Map();
-        for (const { descriptor, scopes } of registration.descriptors) {
-            for (const scope of scopes) {
-                descriptors.set(EnvironmentAttachmentValues.scopeKey(scope), descriptor);
-            }
-        }
-        return descriptors;
-    },
-    /**
-     * Converts a finite startup settlement into registration-scoped parked evidence.
-     *
-     * @param token Identifies the registration.
-     * @param scopes Supplies configured startup scopes.
-     * @param settlement Supplies the finite recovery settlement.
-     * @returns Parked-obligation evidence for the registration.
-     * @internal
-     */
-    startupObligations(token, scopes, settlement) {
-        const units = scopes.map((scope) => EnvironmentAttachmentValues.scopeKey(scope));
-        const obligations = new ParkedDeliveryObligations({
-            registrations: [{ token, obligations: [{ key: "startup", units }] }],
-            generation: [{ key: "generation", units }],
-        });
-        const configured = new Set(units);
-        for (const result of settlement.scopes) {
-            const unit = EnvironmentAttachmentValues.scopeKey(result.scope);
-            if (!configured.has(unit)) {
-                continue;
-            }
-            const owner = { kind: "registration", token };
-            if (result.disposition === "REJECTED") {
-                obligations.park(owner, "startup", [unit], result.cause);
-            }
-            else if (result.disposition === "PARKED") {
-                obligations.parkFulfilledFailed(owner, "startup", [unit]);
-            }
-            else {
-                obligations.fulfilled(owner, "startup", [unit]);
-            }
-        }
-        return obligations;
-    },
-    throwRejected(records, blocked) {
-        if (blocked) {
-            throw new Error("Startup recovery is blocked by an unresolved shared delivery obligation.");
-        }
-        const causes = records.flatMap((record) => (record.hasCause ? [record.cause] : []));
-        if (causes.length === 1) {
-            throw causes[0];
-        }
-        if (causes.length > 1) {
-            throw new AggregateError(causes, "Environment attachment startup recovery failed.");
-        }
-    },
-});
-/**
- * Exposes owner-bound registration-assembly test operations.
- * @internal
- */
-export const EnvironmentAttachmentAccess = Object.freeze({
-    startupObligations(token, scopes, settlement) {
-        return EnvironmentAttachmentAssembly.startupObligations(token, scopes, settlement);
-    },
-});
-class ReportedFailures {
-    #domains = new Set();
-    get size() {
-        return this.#domains.size;
-    }
-    record(domains) {
-        for (const domain of domains) {
-            this.#domains.add(domain);
-        }
-    }
-    overlaps(domains) {
-        return domains.some((domain) => this.#domains.has(domain));
-    }
-    resolve(domains) {
-        for (const domain of domains) {
-            this.#domains.delete(domain);
-        }
-    }
-    clear() {
-        this.#domains.clear();
-    }
-}
-const currentAggregationFailure = Symbol("currentAggregationFailure");
-/**
- *
- * @internal Groups private attachment-state, scope, and failure operations.
- */
-const EnvironmentAttachmentValues = Object.freeze({
-    tenantKey(tenant) {
-        return tenant.tenantId === undefined
-            ? "\u0000"
-            : String(TenantBoundary.from(tenant.tenantId).key);
-    },
-    explicitRetryError() {
-        return new Error("Environment generation rollback requires an explicit retry.");
-    },
-    detachRetryRequiredError() {
-        return new Error("Environment generation detach requires an explicit retry.");
-    },
-    deliveryStopRetryError() {
-        return new Error("Environment delivery stop requires an explicit retry.");
-    },
-    failedStartError(startError, rollbackError) {
-        const rollbackErrors = rollbackError instanceof AggregateError
-            ? rollbackError.errors
-            : [rollbackError];
-        return new AggregateError([
-            EnvironmentAttachmentValues.asError(startError),
-            ...rollbackErrors.map((error) => EnvironmentAttachmentValues.asError(error)),
-        ], "Environment attachment failed and rollback also failed.");
-    },
-    throwFailures(failures, message) {
-        if (failures.length === 1) {
-            throw failures[0];
-        }
-        if (failures.length > 1) {
-            throw new AggregateError(failures, message);
-        }
-    },
-    throwCurrentAggregation(failures) {
-        if (failures.length === 1) {
-            throw failures[0];
-        }
-        if (failures.length > 1) {
-            // Exact arbitrary failure identity is part of the internal retry contract.
-            // eslint-disable-next-line @typescript-eslint/only-throw-error
-            throw Object.freeze({
-                [currentAggregationFailure]: true,
-                causes: Object.freeze([...failures]),
-            });
-        }
-        throw new Error("Environment transition aggregation requires at least one failure.");
-    },
-    currentAggregationCauses(error) {
-        if (typeof error === "object" &&
-            error !== null &&
-            currentAggregationFailure in error &&
-            error[currentAggregationFailure] === true) {
-            return error.causes;
-        }
-        return Object.freeze([error]);
-    },
-    handle(claim, binding, startup, records) {
-        return new AttachedEnvironmentRegistration(claim, binding, startup, records);
-    },
-    readyScope(owner, endpoint, tenant) {
-        return Object.freeze({
-            owner,
-            ready: Object.freeze({
-                ...(tenant.tenantId === undefined ? {} : { tenantId: tenant.tenantId }),
-                label: endpoint.label,
-                targetTypeUrl: endpoint.targetTypeUrl,
-                shard: new ShardIndex(endpoint.shard.index, endpoint.shard.ofTotal),
-            }),
-        });
-    },
-    appendScopes(existing, added) {
-        const scopes = new Map(existing.map((scope) => [EnvironmentAttachmentValues.scopeKey(scope), scope]));
-        for (const scope of added) {
-            scopes.set(EnvironmentAttachmentValues.scopeKey(scope), scope);
-        }
-        return Object.freeze([...scopes.values()]);
-    },
-    scopeKey(scope) {
-        return JSON.stringify([
-            scope.owner.key,
-            scope.ready.tenantId ?? null,
-            scope.ready.label,
-            scope.ready.targetTypeUrl,
-            scope.ready.shard.index,
-            scope.ready.shard.ofTotal,
-        ]);
-    },
-    readyKey(scope) {
-        return JSON.stringify([
-            scope.tenantId ?? null,
-            scope.label,
-            scope.targetTypeUrl,
-            scope.shard.index,
-            scope.shard.ofTotal,
-        ]);
-    },
-    cloneReady(ready) {
-        return Object.freeze({
-            ...(ready.tenantId === undefined ? {} : { tenantId: ready.tenantId }),
-            label: ready.label,
-            targetTypeUrl: ready.targetTypeUrl,
-            shard: new ShardIndex(ready.shard.index, ready.shard.ofTotal),
-        });
-    },
-    emptySettlement() {
-        return Object.freeze({ scopes: Object.freeze([]), pending: Object.freeze([]) });
-    },
-    asError(value) {
-        return value instanceof Error ? value : new Error(String(value));
-    },
-});
-//# sourceMappingURL=environment-attachment.js.map