@fps-games/editor 0.1.8 → 0.2.0-beta.2

package/node_modules/@fps-games/plugin-host/dist/index.js

@@ -0,0 +1,886 @@
+import { defineFpsPluginEntry, defineFpsPluginManifest, defineFpsServiceToken, getFpsPluginEventNamespace, resolveFpsPluginEnvironmentProvides, resolveFpsPluginEnvironmentRequirements, snapshotFpsPluginConfig, } from '@fps-games/plugin-api';
+import semver from 'semver';
+const { satisfies, valid, validRange } = semver;
+function combineErrors(errors, message) {
+    const details = errors.map(error => error instanceof Error ? error.message : String(error)).join('; ');
+    const combined = new Error(`${message} ${details}`);
+    Object.assign(combined, { errors: [...errors] });
+    return combined;
+}
+class Services {
+    constructor(parent) {
+        this.parent = parent;
+        this.values = new Map();
+        this.active = true;
+    }
+    assertActive() { if (!this.active)
+        throw new Error('Service registry is disposed.'); }
+    register(token, value) {
+        return this.registerOwned(token, value, 'host');
+    }
+    registerOwned(token, value, owner) {
+        this.assertActive();
+        if (this.values.has(token.id))
+            throw new Error(`Service already registered in this scope: ${token.id}`);
+        const registration = { value, owner };
+        this.values.set(token.id, registration);
+        return () => { if (this.values.get(token.id) === registration)
+            this.values.delete(token.id); };
+    }
+    has(token) { this.assertActive(); return this.hasId(token.id); }
+    get(token) {
+        this.assertActive();
+        const registration = this.resolve(token.id);
+        if (!registration)
+            throw new Error(`Service not registered: ${token.id}`);
+        return registration.value;
+    }
+    getOptional(token) {
+        this.assertActive();
+        return this.resolve(token.id)?.value;
+    }
+    resolve(id) { return this.values.get(id) ?? this.parent?.resolve(id); }
+    hasId(id) { return this.resolve(id) !== undefined; }
+    hasLocalId(id, owner) { const value = this.values.get(id); return value !== undefined && (owner === undefined || value.owner === owner); }
+    deactivate() { this.values.clear(); this.active = false; }
+}
+class PluginServices {
+    constructor(services, manifest, environment) {
+        this.services = services;
+        this.manifest = manifest;
+        const requires = resolveFpsPluginEnvironmentRequirements(manifest, environment);
+        const provides = resolveFpsPluginEnvironmentProvides(manifest, environment);
+        this.writable = new Set(provides.services ?? []);
+        this.readable = new Set([...(requires.services ?? []), ...this.writable]);
+    }
+    assertReadable(token) {
+        if (!this.readable.has(token.id))
+            throw new Error(`Plugin accessed undeclared service: ${this.manifest.id} -> ${token.id}`);
+    }
+    register(token, value) {
+        if (!this.writable.has(token.id))
+            throw new Error(`Plugin registered undeclared service: ${this.manifest.id} -> ${token.id}`);
+        return this.services.registerOwned(token, value, this.manifest.id);
+    }
+    has(token) { this.assertReadable(token); return this.services.has(token); }
+    get(token) { this.assertReadable(token); return this.services.get(token); }
+    getOptional(token) { this.assertReadable(token); return this.services.getOptional(token); }
+}
+class Commands {
+    constructor(parent, assertExecutionAvailable) {
+        this.parent = parent;
+        this.assertExecutionAvailable = assertExecutionAvailable;
+        this.handlers = new Map();
+        this.activeExecutions = new Map();
+        this.nextExecutionId = 1;
+        this.active = true;
+    }
+    assertActive() { if (!this.active)
+        throw new Error('Command registry is disposed.'); }
+    register(command, handler) {
+        this.assertActive();
+        if (this.handlers.has(command.id))
+            throw new Error(`Command already registered in this scope: ${command.id}`);
+        this.handlers.set(command.id, handler);
+        return () => { if (this.handlers.get(command.id) === handler)
+            this.handlers.delete(command.id); };
+    }
+    async execute(command, input) {
+        return this.executeWithAuthorization(command, input, false);
+    }
+    async executeWithAuthorization(command, input, authorized) {
+        this.assertActive();
+        if (!authorized)
+            this.assertExecutionAvailable?.();
+        const handler = this.handlers.get(command.id);
+        if (handler) {
+            const executionId = this.nextExecutionId++;
+            this.activeExecutions.set(executionId, command.id);
+            try {
+                return await handler(input);
+            }
+            finally {
+                this.activeExecutions.delete(executionId);
+            }
+        }
+        if (this.parent)
+            return this.parent.executeWithAuthorization(command, input, true);
+        throw new Error(`Command not registered: ${command.id}`);
+    }
+    listActiveExecutions() { return [...this.activeExecutions.values()]; }
+    deactivate() { this.handlers.clear(); this.active = false; }
+}
+class Events {
+    constructor(parent, report) {
+        this.parent = parent;
+        this.report = report;
+        this.listeners = new Map();
+        this.active = true;
+    }
+    assertActive() { if (!this.active)
+        throw new Error('Event registry is disposed.'); }
+    subscribe(event, listener) {
+        this.assertActive();
+        const set = this.listeners.get(event.id) ?? new Set();
+        set.add(listener);
+        this.listeners.set(event.id, set);
+        return () => { set.delete(listener); if (!set.size)
+            this.listeners.delete(event.id); };
+    }
+    async deliver(event, payload, errors) {
+        for (const listener of [...(this.listeners.get(event.id) ?? [])]) {
+            try {
+                await listener(payload);
+            }
+            catch (error) {
+                errors.push(error);
+            }
+        }
+        await this.parent?.deliver(event, payload, errors);
+    }
+    async publish(event, payload) {
+        this.assertActive();
+        const errors = [];
+        await this.deliver(event, payload, errors);
+        if (errors.length === 0)
+            return;
+        const messages = errors.map(error => error instanceof Error ? error.message : String(error));
+        try {
+            this.report({
+                code: 'plugin.event.deliveryFailed',
+                message: `Event ${event.id} reported ${errors.length} listener error(s).`,
+                severity: 'error',
+                details: Object.freeze({
+                    eventId: event.id,
+                    listenerErrorCount: errors.length,
+                    listenerErrorMessages: Object.freeze(messages),
+                }),
+            });
+        }
+        catch (reportError) {
+            errors.push(reportError);
+        }
+        const deliveryError = combineErrors(errors, `Event delivery failed: ${event.id}.`);
+        deliveryError.name = 'FpsEventDeliveryError';
+        throw deliveryError;
+    }
+    deactivate() { this.listeners.clear(); this.active = false; }
+}
+function createPluginEventRegistry(events, pluginId) {
+    const namespace = getFpsPluginEventNamespace(pluginId);
+    return Object.freeze({
+        subscribe(event, listener) {
+            return events.subscribe(event, listener);
+        },
+        publish(event, payload) {
+            if (event.ownerPluginId !== pluginId || !event.id.startsWith(namespace)) {
+                return Promise.reject(new Error(`Plugin ${pluginId} may only publish events in namespace ${namespace}*; got ${event.id}`));
+            }
+            return events.publish(event, payload);
+        },
+    });
+}
+const compareIds = (a, b) => a.id < b.id ? -1 : a.id > b.id ? 1 : 0;
+function validateVersion(version, range, consumerId, dependencyId) {
+    if (!valid(version))
+        throw new Error(`Invalid plugin version: ${dependencyId}@${version}`);
+    const normalizedRange = range ?? '*';
+    if (!validRange(normalizedRange))
+        throw new Error(`Invalid plugin version range: ${consumerId} requires ${dependencyId}@${normalizedRange}`);
+    if (!satisfies(version, normalizedRange))
+        throw new Error(`Plugin version mismatch: ${consumerId} requires ${dependencyId}@${normalizedRange}`);
+}
+function order(manifests, environment, inheritedServices, inheritedPlugin) {
+    const allById = new Map();
+    const byId = new Map();
+    const serviceProviders = new Map();
+    for (const manifest of manifests) {
+        const inherited = inheritedPlugin?.(manifest.id);
+        if (inherited && (inherited.version !== manifest.version || inherited.apiVersion !== manifest.apiVersion)) {
+            throw new Error(`Plugin identity mismatch across scopes: ${manifest.id}`);
+        }
+        if (allById.has(manifest.id))
+            throw new Error(`Duplicate plugin id: ${manifest.id}`);
+        allById.set(manifest.id, manifest);
+        if (!manifest.entries[environment])
+            continue;
+        if (!valid(manifest.version))
+            throw new Error(`Invalid plugin version: ${manifest.id}@${manifest.version}`);
+        byId.set(manifest.id, manifest);
+        const provides = resolveFpsPluginEnvironmentProvides(manifest, environment);
+        for (const serviceId of provides.services ?? []) {
+            const previous = serviceProviders.get(serviceId);
+            if (previous)
+                throw new Error(`Duplicate service provider: ${serviceId} (${previous.id}, ${manifest.id})`);
+            if (inheritedServices?.hasLocalId(serviceId)
+                && !inheritedServices.hasLocalId(serviceId, manifest.id)) {
+                throw new Error(`Duplicate service provider: ${serviceId} (host, ${manifest.id})`);
+            }
+            serviceProviders.set(serviceId, manifest);
+        }
+    }
+    const dependencies = (manifest) => {
+        const result = new Map();
+        const requires = resolveFpsPluginEnvironmentRequirements(manifest, environment);
+        for (const requirement of requires.plugins ?? []) {
+            const dependency = byId.get(requirement.id);
+            if (!dependency) {
+                const inherited = inheritedPlugin?.(requirement.id);
+                if (inherited) {
+                    validateVersion(inherited.version, requirement.range, manifest.id, requirement.id);
+                    continue;
+                }
+                const suffix = allById.has(requirement.id) ? ` (${environment} entry unavailable)` : '';
+                throw new Error(`Missing plugin dependency: ${manifest.id} -> ${requirement.id}${suffix}`);
+            }
+            validateVersion(dependency.version, requirement.range, manifest.id, requirement.id);
+            result.set(dependency.id, dependency);
+        }
+        for (const serviceId of requires.services ?? []) {
+            const provider = serviceProviders.get(serviceId);
+            if (provider)
+                result.set(provider.id, provider);
+            else if (!inheritedServices?.hasId(serviceId))
+                throw new Error(`Missing required service: ${manifest.id} -> ${serviceId}`);
+        }
+        return [...result.values()].sort(compareIds);
+    };
+    const visiting = new Set();
+    const visited = new Set();
+    const result = [];
+    const visit = (manifest) => {
+        if (visiting.has(manifest.id))
+            throw new Error(`Plugin dependency cycle at: ${manifest.id}`);
+        if (visited.has(manifest.id))
+            return;
+        visiting.add(manifest.id);
+        for (const dependency of dependencies(manifest))
+            visit(dependency);
+        visiting.delete(manifest.id);
+        visited.add(manifest.id);
+        result.push(manifest);
+    };
+    for (const manifest of [...byId.values()].sort(compareIds))
+        visit(manifest);
+    return result;
+}
+export function resolveFpsPluginManifestOrder(options) {
+    if (!Number.isInteger(options.apiVersion) || options.apiVersion < 1) {
+        throw new Error('Plugin Host apiVersion must be a positive integer.');
+    }
+    const manifests = options.manifests.map(manifest => defineFpsPluginManifest(manifest));
+    const initialServices = new Services();
+    for (const serviceId of options.initialServiceIds ?? []) {
+        initialServices.register(defineFpsServiceToken(serviceId), null);
+    }
+    const result = order(manifests, options.environment, initialServices);
+    for (const manifest of result) {
+        if (manifest.apiVersion !== options.apiVersion) {
+            throw new Error(`Plugin API mismatch: ${manifest.id}`);
+        }
+    }
+    return Object.freeze([...result]);
+}
+function createHost(options, parent) {
+    const pluginConfigs = Object.freeze(Object.fromEntries(Object.entries(options.pluginConfigs ?? {}).map(([pluginId, config]) => [pluginId, snapshotFpsPluginConfig(config, `Plugin config ${pluginId}`)])));
+    options = {
+        ...options,
+        manifests: options.manifests.map(manifest => defineFpsPluginManifest(manifest)),
+        pluginConfigs,
+    };
+    const services = new Services(parent?.services);
+    const commands = new Commands(parent?.commands, () => assertCommandExecutionAvailable());
+    const records = [];
+    const diagnostics = [];
+    const pluginLifecycles = new Map(options.manifests.map(manifest => [
+        manifest.id,
+        manifest.entries[options.environment] ? 'discovered' : 'unavailable',
+    ]));
+    const children = [];
+    const scope = options.scope ?? 'application';
+    let state = 'created';
+    let host;
+    let transitioning = false;
+    let teardownReservationCount = 0;
+    let cleanupMode = null;
+    let activeLifecyclePluginId;
+    const localPlugins = new Map(options.manifests
+        .filter(manifest => manifest.entries[options.environment])
+        .map(manifest => [manifest.id, manifest]));
+    const resolvePlugin = (id) => localPlugins.get(id) ?? parent?.resolvePlugin(id);
+    const retainDiagnostic = (diagnostic) => {
+        diagnostics.push(Object.freeze({
+            code: diagnostic.code,
+            message: diagnostic.message,
+            severity: diagnostic.severity,
+            ...(diagnostic.pluginId ? { pluginId: diagnostic.pluginId } : {}),
+        }));
+        if (diagnostics.length > 200)
+            diagnostics.shift();
+    };
+    const report = (diagnostic, forward = true) => {
+        retainDiagnostic(diagnostic);
+        if (!forward || !options.report)
+            return;
+        try {
+            options.report(diagnostic);
+        }
+        catch (error) {
+            retainDiagnostic({
+                code: 'plugin.report.observerFailed',
+                message: error instanceof Error ? error.message : String(error),
+                severity: 'error',
+                ...(diagnostic.pluginId ? { pluginId: diagnostic.pluginId } : {}),
+            });
+        }
+    };
+    const events = new Events(parent?.events, diagnostic => report(diagnostic));
+    const hasTransitionInTree = () => transitioning || children.some(child => child.hasTransitionInTree());
+    const isTransitioningTree = () => hasTransitionInTree() || parent?.isTransitioningTree() === true;
+    const hasCleanupFailureInTree = () => (state === 'cleanup-failed'
+        || children.some(child => child.hasCleanupFailureInTree()));
+    const isCleanupFailedTree = () => (hasCleanupFailureInTree()
+        || parent?.hasCleanupFailureInTree() === true);
+    const hasTeardownReservationInTree = () => (teardownReservationCount > 0
+        || children.some(child => child.hasTeardownReservationInTree()));
+    const isTeardownReservedTree = () => (hasTeardownReservationInTree()
+        || parent?.isTeardownReservedTree() === true);
+    const listActiveCommandsInTree = () => Object.freeze([
+        ...commands.listActiveExecutions(),
+        ...children.flatMap(child => child.listActiveCommandsInTree()),
+    ]);
+    const listActiveCommandsInLineage = () => Object.freeze([
+        ...commands.listActiveExecutions(),
+        ...(parent?.listActiveCommandsInLineage() ?? []),
+    ]);
+    const assertNoActiveCommandsForTeardown = (operation) => {
+        const activeCommands = Object.freeze([
+            ...(parent?.listActiveCommandsInLineage() ?? []),
+            ...listActiveCommandsInTree(),
+        ]);
+        if (activeCommands.length === 0)
+            return;
+        throw new Error(`Cannot ${operation} Plugin Host while commands are active: ${activeCommands.join(', ')}`);
+    };
+    function assertCommandExecutionAvailable() {
+        if (isTeardownReservedTree()) {
+            throw new Error('Plugin host disposal has been requested; command execution is unavailable.');
+        }
+        if (isCleanupFailedTree()) {
+            throw new Error('Plugin host cleanup is incomplete; command execution is unavailable.');
+        }
+        const treeTransitioning = isTransitioningTree();
+        const starting = state === 'registered' && transitioning && cleanupMode === null;
+        if ((state !== 'started' || treeTransitioning) && !starting) {
+            throw new Error(`Plugin host command execution requires an idle started host, got: ${state}${treeTransitioning ? ' (transitioning)' : ''}.`);
+        }
+    }
+    const assertPublicOperationsAvailable = () => {
+        if (isTeardownReservedTree()) {
+            throw new Error('Plugin host disposal has been requested; public operations are unavailable.');
+        }
+        if (isCleanupFailedTree()) {
+            throw new Error('Plugin host cleanup is incomplete; only stop or dispose may be retried.');
+        }
+        const treeTransitioning = isTransitioningTree();
+        if (state !== 'started' || treeTransitioning) {
+            throw new Error(`Plugin host public operations require an idle started host, got: ${state}${treeTransitioning ? ' (transitioning)' : ''}.`);
+        }
+    };
+    const publicServices = {
+        register(token, value) {
+            assertPublicOperationsAvailable();
+            return services.register(token, value);
+        },
+        has(token) {
+            assertPublicOperationsAvailable();
+            return services.has(token);
+        },
+        get(token) {
+            assertPublicOperationsAvailable();
+            return services.get(token);
+        },
+        getOptional(token) {
+            assertPublicOperationsAvailable();
+            return services.getOptional(token);
+        },
+    };
+    const publicCommands = {
+        register(command, handler) {
+            assertPublicOperationsAvailable();
+            return commands.register(command, handler);
+        },
+        execute(command, input) {
+            assertPublicOperationsAvailable();
+            return commands.execute(command, input);
+        },
+    };
+    const publicEvents = {
+        subscribe(event, listener) {
+            assertPublicOperationsAvailable();
+            return events.subscribe(event, listener);
+        },
+        publish(event, payload) {
+            assertPublicOperationsAvailable();
+            return events.publish(event, payload);
+        },
+    };
+    const inspect = () => {
+        const plugins = options.manifests
+            .map(manifest => {
+            const lifecycle = pluginLifecycles.get(manifest.id) ?? 'unavailable';
+            return Object.freeze({
+                manifest,
+                lifecycle,
+                compatible: manifest.apiVersion === options.apiVersion,
+            });
+        })
+            .sort((left, right) => compareIds(left.manifest, right.manifest));
+        return Object.freeze({
+            environment: options.environment,
+            apiVersion: options.apiVersion,
+            scope,
+            state: hasCleanupFailureInTree() ? 'cleanup-failed' : state,
+            transitioning: isTransitioningTree() || isTeardownReservedTree(),
+            plugins: Object.freeze(plugins),
+            diagnostics: Object.freeze([...diagnostics]),
+        });
+    };
+    const runTransition = async (operation, allowAncestorTransition = false) => {
+        if (transitioning)
+            throw new Error('Plugin host lifecycle transition already in progress.');
+        if (!allowAncestorTransition && parent?.isTransitioningTree())
+            throw new Error('Ancestor plugin scope lifecycle transition already in progress.');
+        transitioning = true;
+        try {
+            return await operation();
+        }
+        finally {
+            transitioning = false;
+        }
+    };
+    for (const initial of options.initialServices ?? [])
+        services.register(initial.token, initial.value);
+    const disposeRecord = async (record, errors) => {
+        if (!record.disposeCompleted) {
+            try {
+                await record.entry.dispose?.(record.context);
+                record.disposeCompleted = true;
+            }
+            catch (error) {
+                errors.push(error);
+                return false;
+            }
+        }
+        for (let index = record.disposers.length - 1; index >= 0; index -= 1) {
+            try {
+                await record.disposers[index]();
+                record.disposers.splice(index, 1);
+            }
+            catch (error) {
+                errors.push(error);
+                break;
+            }
+        }
+        const disposed = record.disposeCompleted && record.disposers.length === 0;
+        if (disposed)
+            pluginLifecycles.set(record.manifest.id, 'disposed');
+        return disposed;
+    };
+    const stopRecords = async (errors) => {
+        for (const record of [...records].reverse()) {
+            if (!record.started)
+                continue;
+            try {
+                await record.entry.stop?.(record.context);
+                record.started = false;
+                pluginLifecycles.set(record.manifest.id, 'stopped');
+            }
+            catch (error) {
+                errors.push(error);
+                break;
+            }
+        }
+    };
+    const cleanup = async (hasCause, cause) => {
+        cleanupMode = 'dispose';
+        const cleanupErrors = [];
+        for (const child of [...children].reverse()) {
+            try {
+                await child.disposeFromParent();
+            }
+            catch (error) {
+                cleanupErrors.push(error);
+                break;
+            }
+        }
+        if (cleanupErrors.length === 0) {
+            await stopRecords(cleanupErrors);
+            if (cleanupErrors.length === 0) {
+                for (let index = records.length - 1; index >= 0; index -= 1) {
+                    const record = records[index];
+                    if (record.started)
+                        continue;
+                    if (await disposeRecord(record, cleanupErrors))
+                        records.splice(index, 1);
+                    else
+                        break;
+                }
+            }
+        }
+        if (cleanupErrors.length === 0) {
+            services.deactivate();
+            commands.deactivate();
+            events.deactivate();
+            state = 'disposed';
+            cleanupMode = null;
+            parent?.removeChild(host);
+        }
+        else {
+            state = 'cleanup-failed';
+        }
+        const errors = [
+            ...(hasCause ? [cause] : []),
+            ...cleanupErrors,
+        ];
+        if (errors.length === 1)
+            throw errors[0];
+        if (errors.length > 1)
+            throw combineErrors(errors, 'Plugin host lifecycle failed and cleanup reported errors:');
+    };
+    host = {
+        get state() { return hasCleanupFailureInTree() ? 'cleanup-failed' : state; },
+        get transitioning() { return isTransitioningTree() || isTeardownReservedTree(); },
+        scope,
+        services: publicServices,
+        commands: publicCommands,
+        events: publicEvents,
+        inspect,
+        createScope(childOptions) {
+            if (isTeardownReservedTree()) {
+                throw new Error('Cannot create a child scope while Plugin Host teardown is reserved.');
+            }
+            if (isCleanupFailedTree()) {
+                throw new Error('Cannot create a child scope while Plugin Host tree is cleanup-failed (cleanup is incomplete).');
+            }
+            const treeTransitioning = isTransitioningTree();
+            if (state !== 'started' || treeTransitioning)
+                throw new Error(`Cannot create a child scope from plugin host state: ${state}${treeTransitioning ? ' (transitioning)' : ''}`);
+            const child = createHost({
+                ...options,
+                scope: childOptions.scope,
+                manifests: childOptions.manifests ?? options.manifests,
+                pluginConfigs: childOptions.pluginConfigs ?? options.pluginConfigs,
+                loadEntry: childOptions.loadEntry ?? options.loadEntry,
+                initialServices: childOptions.initialServices,
+            }, {
+                services,
+                commands,
+                events,
+                getState: () => state,
+                isTransitioningTree,
+                hasCleanupFailureInTree,
+                isTeardownReservedTree,
+                listActiveCommandsInLineage,
+                resolvePlugin,
+                addChild: value => children.push(value),
+                removeChild: value => { const index = children.findIndex(childRecord => childRecord.host === value); if (index >= 0)
+                    children.splice(index, 1); },
+            });
+            return child;
+        },
+        start() {
+            return runTransition(async () => {
+                if (isTeardownReservedTree())
+                    throw new Error('Plugin host cannot start while teardown is reserved.');
+                if (state !== 'created')
+                    throw new Error(`Plugin host cannot start from state: ${state}`);
+                if (parent && parent.getState() !== 'started')
+                    throw new Error(`Child plugin scope cannot start while parent is: ${parent.getState()}`);
+                if (parent?.hasCleanupFailureInTree())
+                    throw new Error('Child plugin scope cannot start while the Plugin Host tree cleanup is incomplete.');
+                try {
+                    const manifests = order(options.manifests, options.environment, services, parent?.resolvePlugin);
+                    for (const manifest of manifests) {
+                        activeLifecyclePluginId = manifest.id;
+                        if (manifest.apiVersion !== options.apiVersion)
+                            throw new Error(`Plugin API mismatch: ${manifest.id}`);
+                        if (!manifest.entries[options.environment])
+                            continue;
+                        const loadedEntry = await options.loadEntry(manifest, options.environment);
+                        if (!loadedEntry)
+                            throw new Error(`Plugin entry could not be loaded: ${manifest.id} (${options.environment})`);
+                        const entry = defineFpsPluginEntry(loadedEntry);
+                        if (entry.pluginId !== manifest.id || entry.environment !== options.environment)
+                            throw new Error(`Plugin entry mismatch: ${manifest.id}`);
+                        const record = {
+                            manifest,
+                            entry,
+                            context: undefined,
+                            disposers: [],
+                            started: false,
+                            disposeCompleted: false,
+                        };
+                        record.context = {
+                            environment: options.environment,
+                            pluginId: manifest.id,
+                            config: options.pluginConfigs?.[manifest.id],
+                            scope,
+                            services: new PluginServices(services, manifest, options.environment),
+                            commands,
+                            events: createPluginEventRegistry(events, manifest.id),
+                            report: diagnostic => report({ ...diagnostic, pluginId: manifest.id }),
+                            add: disposer => record.disposers.push(disposer),
+                        };
+                        records.push(record);
+                        const registered = await entry.register(record.context);
+                        if (registered)
+                            record.disposers.push(registered);
+                        const provides = resolveFpsPluginEnvironmentProvides(manifest, options.environment);
+                        for (const serviceId of provides.services ?? []) {
+                            if (!services.hasLocalId(serviceId, manifest.id))
+                                throw new Error(`Plugin did not register declared service: ${manifest.id} -> ${serviceId}`);
+                        }
+                        pluginLifecycles.set(manifest.id, 'registered');
+                    }
+                    for (const manifest of manifests) {
+                        if (!manifest.entries[options.environment])
+                            continue;
+                        const requires = resolveFpsPluginEnvironmentRequirements(manifest, options.environment);
+                        for (const serviceId of requires.services ?? []) {
+                            if (!services.hasId(serviceId))
+                                throw new Error(`Required service not registered: ${manifest.id} -> ${serviceId}`);
+                        }
+                    }
+                    state = 'registered';
+                    for (const record of records) {
+                        activeLifecyclePluginId = record.manifest.id;
+                        record.started = true;
+                        await record.entry.start?.(record.context);
+                        pluginLifecycles.set(record.manifest.id, 'started');
+                    }
+                    activeLifecyclePluginId = undefined;
+                    state = 'started';
+                }
+                catch (error) {
+                    report({
+                        code: 'plugin.lifecycle.failed',
+                        message: error instanceof Error ? error.message : String(error),
+                        severity: 'error',
+                        ...(activeLifecyclePluginId ? { pluginId: activeLifecyclePluginId } : {}),
+                    }, false);
+                    const activeCommands = listActiveCommandsInTree();
+                    if (activeCommands.length > 0) {
+                        cleanupMode = 'dispose';
+                        state = 'cleanup-failed';
+                        throw combineErrors([
+                            error,
+                            new Error(`Plugin start rollback is waiting for active commands: ${activeCommands.join(', ')}`),
+                        ], 'Plugin host start failed and cleanup is pending:');
+                    }
+                    await cleanup(true, error);
+                }
+            });
+        },
+        stop() {
+            assertNoActiveCommandsForTeardown('stop');
+            return runTransition(async () => {
+                if (state !== 'started' && state !== 'cleanup-failed')
+                    return;
+                if (state === 'cleanup-failed' && cleanupMode === 'dispose') {
+                    throw new Error('Plugin host disposal cleanup is incomplete; dispose must be retried.');
+                }
+                cleanupMode = 'stop';
+                const transitioningChild = children.find(child => child.hasTransitionInTree());
+                if (transitioningChild)
+                    throw new Error(`Child plugin scope lifecycle transition already in progress: ${transitioningChild.host.scope}`);
+                const errors = [];
+                for (const child of [...children].reverse()) {
+                    try {
+                        await child.stopFromParent();
+                    }
+                    catch (error) {
+                        errors.push(error);
+                        break;
+                    }
+                }
+                if (errors.length === 0)
+                    await stopRecords(errors);
+                if (errors.length > 0 || records.some(record => record.started))
+                    state = 'cleanup-failed';
+                else {
+                    state = 'stopped';
+                    cleanupMode = null;
+                }
+                if (errors.length === 1)
+                    throw errors[0];
+                if (errors.length > 1)
+                    throw combineErrors(errors, 'Plugin host stop reported errors:');
+            });
+        },
+        dispose() {
+            assertNoActiveCommandsForTeardown('dispose');
+            return runTransition(async () => {
+                if (state === 'disposed')
+                    return;
+                const transitioningChild = children.find(child => child.hasTransitionInTree());
+                if (transitioningChild)
+                    throw new Error(`Child plugin scope lifecycle transition already in progress: ${transitioningChild.host.scope}`);
+                await cleanup(false);
+            });
+        },
+        reserveTeardown() {
+            if (state === 'disposed') {
+                return Object.assign(() => { }, { assertReady: () => { } });
+            }
+            teardownReservationCount += 1;
+            let active = true;
+            const release = () => {
+                if (!active)
+                    return;
+                active = false;
+                teardownReservationCount -= 1;
+            };
+            return Object.assign(release, {
+                assertReady: () => assertNoActiveCommandsForTeardown('reserve teardown for'),
+            });
+        },
+    };
+    parent?.addChild({
+        host,
+        hasTransitionInTree,
+        hasCleanupFailureInTree,
+        hasTeardownReservationInTree,
+        listActiveCommandsInTree,
+        stopFromParent: () => runTransition(async () => {
+            assertNoActiveCommandsForTeardown('stop');
+            if (state !== 'started' && state !== 'cleanup-failed')
+                return;
+            if (state === 'cleanup-failed' && cleanupMode === 'dispose') {
+                throw new Error('Plugin host disposal cleanup is incomplete; dispose must be retried.');
+            }
+            cleanupMode = 'stop';
+            const transitioningChild = children.find(child => child.hasTransitionInTree());
+            if (transitioningChild)
+                throw new Error(`Child plugin scope lifecycle transition already in progress: ${transitioningChild.host.scope}`);
+            const errors = [];
+            for (const child of [...children].reverse()) {
+                try {
+                    await child.stopFromParent();
+                }
+                catch (error) {
+                    errors.push(error);
+                    break;
+                }
+            }
+            if (errors.length === 0)
+                await stopRecords(errors);
+            if (errors.length > 0 || records.some(record => record.started))
+                state = 'cleanup-failed';
+            else {
+                state = 'stopped';
+                cleanupMode = null;
+            }
+            if (errors.length === 1)
+                throw errors[0];
+            if (errors.length > 1)
+                throw combineErrors(errors, 'Plugin host stop reported errors:');
+        }, true),
+        disposeFromParent: () => runTransition(async () => {
+            assertNoActiveCommandsForTeardown('dispose');
+            if (state === 'disposed')
+                return;
+            const transitioningChild = children.find(child => child.hasTransitionInTree());
+            if (transitioningChild)
+                throw new Error(`Child plugin scope lifecycle transition already in progress: ${transitioningChild.host.scope}`);
+            await cleanup(false);
+        }, true),
+    });
+    return host;
+}
+export function createFpsPluginHost(options) {
+    return createHost(options);
+}
+export function createFpsPluginHostFromEnvironmentModule(options) {
+    const entries = new Map();
+    for (const entry of options.module.entries) {
+        if (entries.has(entry.pluginId))
+            throw new Error(`Duplicate Plugin environment module entry: ${entry.pluginId}`);
+        entries.set(entry.pluginId, entry);
+    }
+    return createFpsPluginHost({
+        environment: options.module.environment,
+        apiVersion: options.apiVersion,
+        scope: options.scope,
+        manifests: options.module.manifests,
+        pluginConfigs: options.module.pluginConfigs,
+        initialServices: options.initialServices,
+        report: options.report,
+        async loadEntry(manifest) {
+            const entry = entries.get(manifest.id);
+            if (!entry)
+                throw new Error(`Plugin environment module entry is missing: ${manifest.id}`);
+            return entry.load();
+        },
+    });
+}
+export function createFpsPluginEnvironmentLifecycle(options) {
+    let host = null;
+    let operationInProgress = null;
+    const assertIdle = (operation) => {
+        if (!operationInProgress)
+            return;
+        throw new Error(`Plugin environment lifecycle cannot ${operation} while ${operationInProgress} is in progress.`);
+    };
+    return {
+        get host() { return host; },
+        start: () => {
+            try {
+                assertIdle('start');
+            }
+            catch (error) {
+                return Promise.reject(error);
+            }
+            operationInProgress = 'start';
+            return (async () => {
+                if (host) {
+                    if (host.state === 'started')
+                        return;
+                    throw new Error(`Plugin environment lifecycle retained a ${host.state} Host; dispose it before restarting.`);
+                }
+                const nextHost = createFpsPluginHostFromEnvironmentModule(options);
+                host = nextHost;
+                try {
+                    await nextHost.start();
+                }
+                catch (error) {
+                    if (host === nextHost && nextHost.state === 'disposed')
+                        host = null;
+                    throw error;
+                }
+            })().finally(() => { operationInProgress = null; });
+        },
+        dispose: () => {
+            try {
+                assertIdle('dispose');
+            }
+            catch (error) {
+                return Promise.reject(error);
+            }
+            operationInProgress = 'dispose';
+            return (async () => {
+                const currentHost = host;
+                if (!currentHost)
+                    return;
+                try {
+                    await currentHost.dispose();
+                }
+                finally {
+                    if (host === currentHost && currentHost.state === 'disposed')
+                        host = null;
+                }
+            })().finally(() => { operationInProgress = null; });
+        },
+    };
+}
+//# sourceMappingURL=index.js.map