maka-agent 0.2.0-dev.3.20260830 → 0.2.0-dev.31.20260913

package/node_modules/@maka/runtime-host/dist/server/plugin-platform.js

@@ -0,0 +1,1148 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you 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
+ *
+ *     http://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 { MakaCompositionLoader, } from '@maka/runtime/plugin-composition-loader';
+import { applyCompositionState, MakaPluginRuntimeError, } from '@maka/runtime/plugin-runtime';
+import { validateExtensionConfiguration } from './extension-package-manifest.js';
+import { recoverExtensionBundleImports } from './extension-bundle.js';
+import { loadPluginCompositionPatch } from './plugin-composition-patch.js';
+import { HostPluginCompositionStore, HostPluginCompositionStoreError, } from './plugin-composition-store.js';
+import { TrustedPluginPackageLoader } from './plugin-package-loader.js';
+import { PluginPackageStore, PluginPackageStoreError } from './plugin-package-store.js';
+export class HostPluginPlatformError extends Error {
+    code;
+    name = 'HostPluginPlatformError';
+    constructor(code, message, options) {
+        super(message, options);
+        this.code = code;
+    }
+}
+/**
+ * Runtime Host's sole authority for trusted Plugin packages and Entry composition.
+ * Package layers and user overlays are durable; the desired Entry Tree is derived from them.
+ */
+export class HostPluginPlatform {
+    controlDirectory;
+    #composition;
+    #packages;
+    #packageLoader;
+    #store;
+    #tools;
+    #systemPrompt;
+    #commands;
+    #authority = emptyCompositionAuthority();
+    #desired = emptyCompositionState();
+    #mutation = Promise.resolve();
+    #phase = 'new';
+    #recoveryStarted = false;
+    #recoveryComplete = false;
+    #drainRequested = false;
+    #convergence = 'unknown';
+    #fence;
+    #reconcileTimer;
+    #reconcileDelayMs = 250;
+    #failures = Object.freeze([]);
+    #structuralDependencies = new Map();
+    constructor(controlDirectory, options = {}) {
+        this.controlDirectory = controlDirectory;
+        this.#composition = options.composition ?? new MakaCompositionLoader();
+        this.#packages = options.packages ?? new PluginPackageStore(controlDirectory);
+        this.#packageLoader =
+            options.packageLoader ?? new TrustedPluginPackageLoader(controlDirectory, this.#packages);
+        this.#store = options.store ?? new HostPluginCompositionStore(controlDirectory);
+        this.#tools = options.tools;
+        this.#systemPrompt = options.systemPrompt;
+        this.#commands = options.commands;
+    }
+    async recover() {
+        if (this.#recoveryStarted ||
+            (this.#phase !== 'new' && !(this.#phase === 'draining' && this.#drainRequested))) {
+            throw new HostPluginPlatformError('recovery_failed', `Plugin Platform cannot recover from phase ${this.#phase}`);
+        }
+        this.#recoveryStarted = true;
+        if (!this.#drainRequested)
+            this.#phase = 'recovering';
+        await this.#serialize(async () => {
+            try {
+                const storedAuthority = (await this.#store.read()) ?? emptyCompositionAuthority();
+                await recoverExtensionBundleImports(this.controlDirectory);
+                await this.#packages.recover(storedAuthority.generation);
+                await this.#packageLoader.collectGarbage();
+                const packageFailures = [];
+                for (const extensionId of await this.#packages.identities()) {
+                    let loaded;
+                    try {
+                        loaded = await this.#packageLoader.load(extensionId);
+                        await this.#composition.install(loaded);
+                    }
+                    catch (error) {
+                        if (loaded)
+                            await this.#packageLoader.release(loaded).catch(() => undefined);
+                        packageFailures.push(Object.freeze({
+                            extensionId,
+                            diagnostic: boundedDiagnostic(error),
+                        }));
+                    }
+                }
+                const projection = await this.#deriveDesired(storedAuthority, 'recovery');
+                const entryFailures = await this.#recoverDesiredRuntime(projection.desired);
+                this.#failures = Object.freeze([
+                    ...packageFailures,
+                    ...projection.failures,
+                    ...entryFailures.map((failure) => Object.freeze({ entryId: failure.entryId, diagnostic: failure.diagnostic })),
+                ]);
+                this.#authority = storedAuthority;
+                this.#desired = projection.desired;
+                this.#structuralDependencies = projection.structuralDependencies;
+                this.#convergence = this.#failures.length > 0 ? 'diverged' : 'converged';
+                this.#recoveryComplete = true;
+                this.#phase = this.#drainRequested
+                    ? 'draining'
+                    : this.#failures.length > 0
+                        ? 'degraded'
+                        : 'ready';
+                if (this.#failures.length > 0)
+                    this.#scheduleReconcile();
+            }
+            catch (error) {
+                this.#fence = asError(error);
+                this.#recoveryComplete = true;
+                this.#phase = 'fenced';
+                this.#convergence = 'unknown';
+            }
+        });
+    }
+    async installPackage(sourcePath) {
+        this.#assertMutable();
+        return await this.#serializeMutable(async () => {
+            let prepared;
+            try {
+                prepared = await this.#packages.prepareInstall(sourcePath);
+            }
+            catch (error) {
+                if (error instanceof PluginPackageStoreError && error.code === 'commit_outcome_unknown') {
+                    throw this.#fenceUnknownPackageOutcome(error, 'preparation');
+                }
+                throw error;
+            }
+            let loaded;
+            let authorityCommitted = false;
+            let packageCommitted = false;
+            let runtimeAdoptionStarted = false;
+            try {
+                const compositionPatch = await loadPluginCompositionPatch(prepared.installed);
+                loaded = await this.#packageLoader.loadInstalled(prepared.installed);
+                const alreadyInstalled = this.#composition
+                    .installedPackages()
+                    .some(({ packageId }) => packageId === prepared.installed.extensionId);
+                const layerPlan = await this.#planPackageLayer(prepared.installed.extensionId, compositionPatch, prepared.installed.manifest);
+                await prepared.publish(this.#authority.generation, layerPlan.planned.generation);
+                await this.#commitDesiredAuthority(layerPlan.planned, layerPlan.packageLayers, this.#authority.overlays);
+                authorityCommitted = true;
+                this.#structuralDependencies = layerPlan.structuralDependencies;
+                await prepared.commit();
+                packageCommitted = true;
+                this.#clearPackageFailure(prepared.installed.extensionId);
+                runtimeAdoptionStarted = true;
+                const failures = await this.#adoptRuntimePackage(prepared.installed.extensionId, loaded, layerPlan.planned, alreadyInstalled);
+                await this.#publishEntryFailures(failures);
+                this.#settleConvergence(failures.length === 0);
+                return Object.freeze({
+                    extensionId: prepared.installed.extensionId,
+                    ...this.#receipt('complete'),
+                });
+            }
+            catch (error) {
+                if (authorityCommitted) {
+                    if (loaded && !runtimeAdoptionStarted) {
+                        await this.#packageLoader.release(loaded).catch(() => undefined);
+                    }
+                    this.#recordPackageFailure(prepared.installed.extensionId, error);
+                    this.#settleConvergence(false);
+                    return Object.freeze({
+                        extensionId: prepared.installed.extensionId,
+                        ...this.#receipt(packageCommitted ? 'complete' : 'pending'),
+                    });
+                }
+                if (error instanceof PluginPackageStoreError && error.code === 'commit_outcome_unknown') {
+                    if (loaded)
+                        await this.#packageLoader.release(loaded).catch(() => undefined);
+                    throw this.#fenceUnknownPackageOutcome(error, 'publication');
+                }
+                if (error instanceof HostPluginPlatformError && error.code === 'commit_outcome_unknown') {
+                    if (loaded)
+                        await this.#packageLoader.release(loaded).catch(() => undefined);
+                    throw error;
+                }
+                try {
+                    await prepared.rollback();
+                }
+                catch (rollbackError) {
+                    if (loaded)
+                        await this.#packageLoader.release(loaded).catch(() => undefined);
+                    if (rollbackError instanceof PluginPackageStoreError &&
+                        rollbackError.code === 'commit_outcome_unknown') {
+                        throw this.#fenceUnknownPackageOutcome(rollbackError, 'rollback');
+                    }
+                    this.#fence = asError(rollbackError);
+                    this.#phase = 'fenced';
+                    throw new HostPluginPlatformError('persistence_failed', 'Plugin package installation and stored-package rollback both failed', { cause: new AggregateError([error, rollbackError]) });
+                }
+                if (loaded)
+                    await this.#packageLoader.release(loaded).catch(() => undefined);
+                throw error;
+            }
+        });
+    }
+    async reloadPackage(extensionId) {
+        this.#assertMutable();
+        return await this.#serializeMutable(async () => {
+            const loaded = await this.#packageLoader.load(extensionId);
+            let adoptionStarted = false;
+            try {
+                await this.#validateDesired(this.desiredComposition());
+                adoptionStarted = true;
+                const failures = await this.#adoptRuntimePackage(extensionId, loaded, this.#desired, true);
+                await this.#publishEntryFailures(failures);
+                this.#clearPackageFailure(extensionId);
+                this.#settleConvergence(failures.length === 0);
+            }
+            catch (error) {
+                if (!adoptionStarted)
+                    await this.#packageLoader.release(loaded).catch(() => undefined);
+                this.#recordPackageFailure(extensionId, error);
+                this.#settleConvergence(false);
+            }
+            return this.#receipt('complete');
+        });
+    }
+    async uninstallPackage(extensionId) {
+        this.#assertMutable();
+        return await this.#serializeMutable(async () => {
+            const structuralDependent = this.#structuralDependent(extensionId);
+            if (structuralDependent) {
+                throw new MakaPluginRuntimeError('package_in_use', `Plugin package is structurally required by ${structuralDependent}`);
+            }
+            const manifestDependent = await this.#manifestDependentPackage(extensionId);
+            if (manifestDependent) {
+                throw new MakaPluginRuntimeError('package_in_use', `Plugin package is required by package ${manifestDependent}`);
+            }
+            const packageLayers = this.#authority.packageLayers.filter((item) => item !== extensionId);
+            const candidateAuthority = compositionAuthority(this.#authority.generation +
+                (packageLayers.length === this.#authority.packageLayers.length ? 0 : 1), packageLayers, this.#authority.overlays);
+            const projection = await this.#deriveDesired(candidateAuthority, 'strict');
+            const desiredUser = compositionEntries(projection.desired).find((entry) => entry.packageId === extensionId);
+            if (desiredUser) {
+                throw new MakaPluginRuntimeError('package_in_use', `Plugin package is used by desired entry ${desiredUser.id}`);
+            }
+            const dependent = await this.#desiredPackageDependent(extensionId, projection.desired);
+            if (dependent) {
+                throw new MakaPluginRuntimeError('package_in_use', `Plugin package is required by desired entry ${dependent.id}`);
+            }
+            if (packageLayers.length !== this.#authority.packageLayers.length) {
+                await this.#commitDesiredAuthority(projection.desired, packageLayers, this.#authority.overlays);
+                this.#structuralDependencies = projection.structuralDependencies;
+            }
+            const installedInRuntime = this.#composition
+                .installedPackages()
+                .some(({ packageId }) => packageId === extensionId);
+            const pkg = installedInRuntime ? this.#composition.package(extensionId) : undefined;
+            const postCommitErrors = [];
+            const failures = await this.#recoverDesiredRuntime(projection.desired).catch((error) => {
+                postCommitErrors.push(error);
+                return Object.freeze([]);
+            });
+            await this.#publishEntryFailures(failures);
+            if (failures.length > 0)
+                postCommitErrors.push(new Error('Runtime convergence failed'));
+            if (pkg) {
+                await this.#composition
+                    .uninstall(extensionId)
+                    .catch((error) => postCommitErrors.push(error));
+            }
+            await this.#packages.uninstall(extensionId).catch((error) => postCommitErrors.push(error));
+            if (pkg)
+                await this.#releaseGeneration(pkg);
+            if (postCommitErrors.length > 0) {
+                this.#recordPackageFailure(extensionId, new AggregateError(postCommitErrors));
+                this.#settleConvergence(false);
+                return this.#receipt('pending');
+            }
+            this.#clearPackageFailure(extensionId);
+            this.#settleConvergence(true);
+            return this.#receipt('complete');
+        });
+    }
+    async apply(input) {
+        this.#assertMutable();
+        return await this.#serializeMutable(async () => {
+            let normalizedInput;
+            let projection;
+            try {
+                normalizedInput = await this.#normalizeApplyInput(this.#desired, input);
+                const nextAuthority = compositionAuthority(this.#authority.generation + (normalizedInput.operations.length > 0 ? 1 : 0), this.#authority.packageLayers, Object.freeze([...this.#authority.overlays, ...normalizedInput.operations]));
+                projection = await this.#deriveDesired(nextAuthority, 'strict');
+            }
+            catch (error) {
+                throw new HostPluginPlatformError('mutation_failed', 'Plugin composition mutation failed', {
+                    cause: error,
+                });
+            }
+            const next = compositionAuthority(projection.desired.generation, this.#authority.packageLayers, Object.freeze([...this.#authority.overlays, ...normalizedInput.operations]));
+            try {
+                await this.#store.replace(next);
+                this.#authority = next;
+                this.#desired = projection.desired;
+                this.#structuralDependencies = projection.structuralDependencies;
+            }
+            catch (error) {
+                if (error instanceof HostPluginCompositionStoreError &&
+                    error.code === 'commit_outcome_unknown') {
+                    this.#fence = error;
+                    this.#phase = 'fenced';
+                    throw new HostPluginPlatformError('commit_outcome_unknown', 'Plugin composition commit outcome is unknown; Plugin Platform was fenced', { cause: error });
+                }
+                throw new HostPluginPlatformError('persistence_failed', 'Plugin composition persistence failed; Runtime state was not changed', { cause: error });
+            }
+            try {
+                const failures = await this.#recoverDesiredRuntime(projection.desired);
+                await this.#publishEntryFailures(failures);
+                this.#settleConvergence(failures.length === 0);
+                return this.#receipt('complete');
+            }
+            catch (error) {
+                await this.#publishEntryFailures(operationFailures(normalizedInput, error));
+                this.#settleConvergence(false);
+                return this.#receipt('complete');
+            }
+        });
+    }
+    desiredComposition() {
+        this.#assertReadable();
+        return this.#desired;
+    }
+    failures() {
+        this.#assertReadable();
+        return this.#failures;
+    }
+    inspect(rootId) {
+        this.#assertReadable();
+        return this.#composition.inspectTree(rootId);
+    }
+    inspectTools(rootId) {
+        this.#assertReadable();
+        return this.#tools?.inspect(rootId) ?? Object.freeze([]);
+    }
+    inspectSystemPrompt(rootId) {
+        this.#assertReadable();
+        return this.#systemPrompt?.inspect(rootId) ?? Object.freeze([]);
+    }
+    inspectCommands(rootId) {
+        this.#assertReadable();
+        return this.#commands?.inspect(rootId) ?? Object.freeze([]);
+    }
+    async status() {
+        this.#assertReadable();
+        return Object.freeze({
+            phase: this.#phase,
+            authorityEpoch: this.#authority.generation,
+            convergence: this.#convergence,
+            installedPackageCount: (await this.#packages.identities()).length,
+            layeredPackageCount: this.#authority.packageLayers.length,
+            desiredEntryCount: compositionEntries(this.#desired).length,
+            liveEntryCount: countInspections(this.#composition.inspectTree()),
+            failureCount: this.#failures.length,
+            fenceDiagnostic: this.#fence ? boundedDiagnostic(this.#fence) : null,
+        });
+    }
+    async packageProjections() {
+        this.#assertReadable();
+        const requiredBy = new Map();
+        for (const [actor, dependencies] of this.#structuralDependencies) {
+            if (actor.startsWith('@'))
+                continue;
+            for (const dependency of dependencies) {
+                const users = requiredBy.get(dependency) ?? new Set();
+                users.add(actor);
+                requiredBy.set(dependency, users);
+            }
+        }
+        const installedPackages = await Promise.all((await this.#packages.identities()).map((extensionId) => this.#packages.load(extensionId)));
+        for (const installed of installedPackages) {
+            for (const dependency of installed.manifest.dependencies) {
+                const users = requiredBy.get(dependency.id) ?? new Set();
+                users.add(installed.extensionId);
+                requiredBy.set(dependency.id, users);
+            }
+        }
+        const projections = [];
+        for (const installed of installedPackages) {
+            const extensionId = installed.extensionId;
+            projections.push(Object.freeze({
+                extensionId,
+                contentDigest: installed.contentDigest,
+                displayName: installed.manifest.displayName,
+                ...(installed.manifest.description
+                    ? { description: installed.manifest.description }
+                    : {}),
+                dependencies: Object.freeze(installed.manifest.dependencies.map(({ id }) => id)),
+                structuralDependencies: Object.freeze([...(this.#structuralDependencies.get(extensionId) ?? [])].sort()),
+                requiredBy: Object.freeze([...(requiredBy.get(extensionId) ?? [])].sort()),
+            }));
+        }
+        return Object.freeze(projections);
+    }
+    async exportPackage(extensionId, targetPath) {
+        await this.read(() => this.#packages.export(extensionId, targetPath));
+    }
+    async reconcile() {
+        this.#assertMutable();
+        return await this.#serializeMutable(() => this.#reconcileNow());
+    }
+    read(operation) {
+        this.#assertReadable();
+        return this.#serialize(async () => {
+            this.#assertReadable();
+            return await operation();
+        });
+    }
+    beginDrain() {
+        if (this.#phase === 'closed')
+            return;
+        this.#drainRequested = true;
+        this.#phase = 'draining';
+    }
+    async close() {
+        if (this.#phase === 'closed')
+            return;
+        this.#drainRequested = true;
+        this.#phase = 'draining';
+        if (this.#reconcileTimer)
+            clearTimeout(this.#reconcileTimer);
+        this.#reconcileTimer = undefined;
+        const errors = [];
+        try {
+            await this.#mutation;
+        }
+        catch (error) {
+            errors.push(error);
+        }
+        try {
+            await this.#composition.close();
+        }
+        catch (error) {
+            errors.push(error);
+        }
+        try {
+            await this.#packageLoader.close();
+        }
+        catch (error) {
+            errors.push(error);
+        }
+        this.#phase = 'closed';
+        if (errors.length > 0) {
+            throw new AggregateError(errors, 'Unable to close every Plugin Platform resource');
+        }
+    }
+    async #planPackageLayer(extensionId, patch, manifest) {
+        const previousIndex = this.#authority.packageLayers.indexOf(extensionId);
+        const packageLayers = this.#authority.packageLayers.filter((item) => item !== extensionId);
+        const nextIndex = previousIndex < 0 ? packageLayers.length : previousIndex;
+        packageLayers.splice(nextIndex, 0, extensionId);
+        const candidate = compositionAuthority(this.#authority.generation + 1, packageLayers, this.#authority.overlays);
+        const projection = await this.#deriveDesired(candidate, 'strict', {
+            extensionId,
+            patch,
+            manifest,
+        });
+        return {
+            planned: projection.desired,
+            packageLayers,
+            structuralDependencies: projection.structuralDependencies,
+        };
+    }
+    async #deriveDesired(authority, policy, override) {
+        let working = emptyCompositionState();
+        let owners = new Map();
+        let dependencies = new Map();
+        const failures = [];
+        const applyLayer = async (actor, input, manifestOverride) => {
+            let candidate = working;
+            const candidateOwners = new Map(owners);
+            const candidateDependencies = cloneDependencyGraph(dependencies);
+            const applyOperation = async (operation) => {
+                recordStructuralDependencies(candidate, candidateOwners, candidateDependencies, actor, operation);
+                const previous = candidate;
+                candidate = applyCompositionState(candidate, { operations: [operation] });
+                updateEntryOwners(previous, candidateOwners, actor, operation);
+            };
+            if (policy === 'strict') {
+                const normalized = await this.#normalizeApplyInput(candidate, input, manifestOverride);
+                for (const operation of normalized.operations)
+                    await applyOperation(operation);
+            }
+            else {
+                for (const operation of input.operations) {
+                    try {
+                        const normalized = await this.#normalizeApplyInput(candidate, { operations: [operation] }, manifestOverride);
+                        await applyOperation(normalized.operations[0]);
+                    }
+                    catch (error) {
+                        try {
+                            await applyOperation(operation);
+                        }
+                        catch {
+                            // A structurally invalid operation cannot contribute to the
+                            // recoverable desired tree, but its diagnostic is retained.
+                        }
+                        const identity = overlayFailureIdentity([operation]);
+                        failures.push(Object.freeze({
+                            ...(actor.startsWith('@') ? { entryId: identity } : { extensionId: actor }),
+                            diagnostic: boundedDiagnostic(error),
+                        }));
+                    }
+                }
+            }
+            if (!actor.startsWith('@') && manifestOverride) {
+                const inferred = [...(candidateDependencies.get(actor) ?? [])].sort();
+                const declared = [...(manifestOverride.composition?.structuralDependencies ?? [])].sort();
+                if (inferred.length !== declared.length ||
+                    inferred.some((dependency, index) => dependency !== declared[index])) {
+                    throw new MakaPluginRuntimeError('invalid_package', `Plugin package ${actor} structural dependencies do not match its composition patch`);
+                }
+            }
+            working = candidate;
+            owners = candidateOwners;
+            dependencies = candidateDependencies;
+        };
+        for (const extensionId of authority.packageLayers) {
+            try {
+                const installed = override?.extensionId === extensionId
+                    ? undefined
+                    : await this.#packages.load(extensionId);
+                const patch = override?.extensionId === extensionId
+                    ? override.patch
+                    : await loadPluginCompositionPatch(installed);
+                const manifest = override?.extensionId === extensionId ? override.manifest : installed.manifest;
+                if (patch) {
+                    await applyLayer(extensionId, patch, manifest);
+                }
+            }
+            catch (error) {
+                if (policy === 'strict')
+                    throw error;
+                failures.push(Object.freeze({ extensionId, diagnostic: boundedDiagnostic(error) }));
+            }
+        }
+        if (authority.overlays.length > 0) {
+            try {
+                await applyLayer('@user-overlay', { operations: authority.overlays });
+            }
+            catch (error) {
+                if (policy === 'strict')
+                    throw error;
+                failures.push(Object.freeze({
+                    entryId: overlayFailureIdentity(authority.overlays),
+                    diagnostic: boundedDiagnostic(error),
+                }));
+            }
+        }
+        let desired = compositionWithGeneration(working, authority.generation);
+        if (policy === 'strict')
+            await this.#validateDesired(desired, override?.manifest);
+        else
+            desired = await this.#normalizeCompositionConfigurations(desired);
+        return Object.freeze({
+            desired,
+            failures: Object.freeze(failures),
+            structuralDependencies: freezeDependencyGraph(dependencies),
+        });
+    }
+    async #commitDesiredAuthority(planned, packageLayers, overlays) {
+        const next = compositionAuthority(planned.generation, packageLayers, overlays);
+        try {
+            await this.#store.replace(next);
+            this.#authority = next;
+            this.#desired = planned;
+        }
+        catch (error) {
+            if (error instanceof HostPluginCompositionStoreError &&
+                error.code === 'commit_outcome_unknown') {
+                this.#fence = error;
+                this.#phase = 'fenced';
+                throw new HostPluginPlatformError('commit_outcome_unknown', 'Plugin composition commit outcome is unknown; Plugin Platform was fenced', { cause: error });
+            }
+            throw new HostPluginPlatformError('persistence_failed', 'Plugin composition persistence failed; Runtime state was not changed', { cause: error });
+        }
+    }
+    async #validateDesired(state, manifestOverride) {
+        const records = compositionEntryRecords(state);
+        for (const record of records) {
+            await this.#validateEntry(record.entry, !record.disabled, manifestOverride);
+            await this.#validateActiveDependencies(record, records, manifestOverride);
+        }
+    }
+    async #normalizeApplyInput(desired, input, manifestOverride) {
+        if (input.baseGeneration !== undefined && input.baseGeneration !== desired.generation) {
+            throw new MakaPluginRuntimeError('invalid_entry', `Composition generation changed from ${input.baseGeneration} to ${desired.generation}`);
+        }
+        let working = desired;
+        const operations = [];
+        for (const operation of input.operations) {
+            let normalized;
+            if (operation.type === 'insert') {
+                normalized = Object.freeze({
+                    ...operation,
+                    entry: await this.#normalizeEntryConfiguration(operation.entry, true, manifestOverride),
+                });
+            }
+            else if (operation.type === 'update') {
+                const current = findCompositionEntry(working, operation.entryId);
+                if (!current) {
+                    throw new MakaPluginRuntimeError('entry_not_found', `Composition entry not found: ${operation.entryId}`);
+                }
+                const effective = Object.freeze({ ...current, ...operation.patch });
+                const configured = await this.#normalizeEntryConfiguration(effective, false, manifestOverride);
+                normalized = Object.freeze({
+                    ...operation,
+                    patch: Object.freeze({ ...operation.patch, config: configured.config }),
+                });
+            }
+            else {
+                normalized = operation;
+            }
+            operations.push(normalized);
+            const advanced = applyCompositionState(working, { operations: [normalized] });
+            working = compositionWithGeneration(advanced, desired.generation);
+        }
+        return Object.freeze({
+            ...(input.baseGeneration === undefined ? {} : { baseGeneration: input.baseGeneration }),
+            operations: Object.freeze(operations),
+        });
+    }
+    async #normalizeCompositionConfigurations(state) {
+        const normalize = async (entry) => {
+            let configured = entry;
+            try {
+                configured = await this.#normalizeEntryConfiguration(entry, false);
+            }
+            catch {
+                // Recovery records malformed or unavailable package configuration as
+                // an Entry failure below instead of failing the Runtime Host.
+            }
+            return Object.freeze({
+                ...configured,
+                children: Object.freeze(await Promise.all((entry.children ?? []).map(normalize))),
+            });
+        };
+        const sessions = await Promise.all(Object.entries(state.roots.sessions).map(async ([scopeId, entries]) => [scopeId, Object.freeze(await Promise.all(entries.map(normalize)))]));
+        return Object.freeze({
+            schemaVersion: 1,
+            generation: state.generation,
+            roots: Object.freeze({
+                profile: Object.freeze(await Promise.all(state.roots.profile.map(normalize))),
+                desktopUi: Object.freeze(await Promise.all(state.roots.desktopUi.map(normalize))),
+                sessions: Object.freeze(Object.fromEntries(sessions)),
+            }),
+        });
+    }
+    async #normalizeEntryConfiguration(entry, recursive = true, manifestOverride) {
+        const config = entry.packageId
+            ? validateExtensionConfiguration((await this.#packageManifest(entry.packageId, manifestOverride)).configuration, entry.config)
+            : scalarConfiguration(entry.config);
+        return Object.freeze({
+            ...entry,
+            config,
+            ...(recursive
+                ? {
+                    children: Object.freeze(await Promise.all((entry.children ?? []).map((child) => this.#normalizeEntryConfiguration(child, true, manifestOverride)))),
+                }
+                : {}),
+        });
+    }
+    async #desiredValidationFailures(state) {
+        const failures = [];
+        const records = compositionEntryRecords(state);
+        for (const record of records) {
+            try {
+                await this.#validateEntry(record.entry, !record.disabled);
+                await this.#validateActiveDependencies(record, records);
+            }
+            catch (error) {
+                failures.push(Object.freeze({ entryId: record.entry.id, diagnostic: boundedDiagnostic(error) }));
+            }
+        }
+        return Object.freeze(failures);
+    }
+    async #validateEntry(entry, active = entry.disabled !== true, manifestOverride) {
+        if (!entry.packageId)
+            return;
+        const manifests = new Map();
+        const visiting = new Set();
+        const visited = new Set();
+        const visit = async (extensionId) => {
+            if (visited.has(extensionId))
+                return;
+            if (visiting.has(extensionId)) {
+                throw new MakaPluginRuntimeError('dependency_cycle', `Plugin package dependency cycle includes ${extensionId}`);
+            }
+            visiting.add(extensionId);
+            let manifest = manifests.get(extensionId);
+            if (!manifest) {
+                manifest = await this.#packageManifest(extensionId, manifestOverride);
+                manifests.set(extensionId, manifest);
+            }
+            for (const dependency of manifest.dependencies)
+                await visit(dependency.id);
+            visiting.delete(extensionId);
+            visited.add(extensionId);
+        };
+        const manifest = await this.#packageManifest(entry.packageId, manifestOverride);
+        validateExtensionConfiguration(manifest.configuration, entry.config);
+        if (active)
+            await visit(entry.packageId);
+    }
+    async #validateActiveDependencies(record, records, manifestOverride) {
+        if (record.disabled || !record.entry.packageId)
+            return;
+        const manifest = await this.#packageManifest(record.entry.packageId, manifestOverride);
+        for (const dependency of manifest.dependencies) {
+            if (!records.some((candidate) => candidate.rootId === record.rootId &&
+                !candidate.disabled &&
+                candidate.entry.packageId === dependency.id)) {
+                throw new MakaPluginRuntimeError('package_not_found', `Required dependency ${dependency.id} is not active in ${record.rootId}`);
+            }
+        }
+    }
+    async #packageManifest(extensionId, manifestOverride) {
+        return manifestOverride?.id === extensionId
+            ? manifestOverride
+            : (await this.#packages.load(extensionId)).manifest;
+    }
+    async #recoverDesiredRuntime(desired) {
+        let failures = new Map((await this.#desiredValidationFailures(desired)).map((failure) => [failure.entryId, failure]));
+        for (;;) {
+            const recovered = await this.#composition.recoverComposition(withoutEntries(desired, new Set(failures.keys())));
+            for (const failure of recovered)
+                failures.set(failure.entryId, failure);
+            const expanded = await this.#expandDependencyFailures(desired, [...failures.values()]);
+            if (expanded.length === failures.size)
+                return Object.freeze([...failures.values()]);
+            failures = new Map(expanded.map((failure) => [failure.entryId, failure]));
+        }
+    }
+    async #expandDependencyFailures(state, initial) {
+        const failures = new Map(initial.map((failure) => [failure.entryId, failure]));
+        const records = compositionEntryRecords(state);
+        let changed = true;
+        while (changed) {
+            changed = false;
+            for (const record of records) {
+                if (record.disabled || !record.entry.packageId || failures.has(record.entry.id))
+                    continue;
+                const manifest = (await this.#packages.load(record.entry.packageId)).manifest;
+                for (const dependency of manifest.dependencies) {
+                    const candidates = records.filter((candidate) => candidate.rootId === record.rootId &&
+                        !candidate.disabled &&
+                        candidate.entry.packageId === dependency.id);
+                    if (candidates.length > 0 && candidates.every(({ entry }) => failures.has(entry.id))) {
+                        failures.set(record.entry.id, Object.freeze({
+                            entryId: record.entry.id,
+                            diagnostic: `Required dependency ${dependency.id} failed in ${record.rootId}`,
+                        }));
+                        changed = true;
+                        break;
+                    }
+                }
+            }
+        }
+        return Object.freeze([...failures.values()]);
+    }
+    async #desiredPackageDependent(extensionId, desired = this.desiredComposition()) {
+        const dependsOn = async (packageId, visited) => {
+            if (packageId === extensionId)
+                return true;
+            if (visited.has(packageId))
+                return false;
+            visited.add(packageId);
+            const manifest = (await this.#packages.load(packageId)).manifest;
+            for (const dependency of manifest.dependencies) {
+                if (await dependsOn(dependency.id, visited))
+                    return true;
+            }
+            return false;
+        };
+        for (const entry of compositionEntries(desired)) {
+            if (entry.packageId &&
+                entry.packageId !== extensionId &&
+                entry.disabled !== true &&
+                (await dependsOn(entry.packageId, new Set()))) {
+                return entry;
+            }
+        }
+        return undefined;
+    }
+    async #manifestDependentPackage(extensionId) {
+        for (const candidateId of this.#authority.packageLayers) {
+            if (candidateId === extensionId)
+                continue;
+            const manifest = (await this.#packages.load(candidateId)).manifest;
+            if (manifest.dependencies.some(({ id }) => id === extensionId))
+                return candidateId;
+        }
+        return undefined;
+    }
+    async #publishEntryFailures(failures) {
+        const packageFailures = this.#failures.filter((failure) => failure.entryId === undefined);
+        this.#failures = Object.freeze([
+            ...packageFailures,
+            ...failures.map((failure) => Object.freeze({ entryId: failure.entryId, diagnostic: failure.diagnostic })),
+        ]);
+    }
+    async #adoptRuntimePackage(extensionId, loaded, desired, replacing) {
+        let installed = false;
+        try {
+            if (replacing) {
+                const previous = this.#composition.package(extensionId);
+                const detached = withoutPackageEntries(desired, extensionId);
+                await this.#recoverDesiredRuntime(detached);
+                await this.#composition.uninstall(extensionId);
+                await this.#releaseGeneration(previous);
+            }
+            await this.#composition.install(loaded);
+            installed = true;
+            return await this.#recoverDesiredRuntime(desired);
+        }
+        catch (error) {
+            if (!installed)
+                await this.#packageLoader.release(loaded).catch(() => undefined);
+            throw error;
+        }
+    }
+    async #releaseGeneration(pkg) {
+        try {
+            await this.#packageLoader.release(pkg);
+        }
+        catch (error) {
+            this.#composition.root.logger.warn('Unable to remove retired Plugin generation', error);
+        }
+    }
+    #clearPackageFailure(extensionId) {
+        this.#failures = Object.freeze(this.#failures.filter((failure) => failure.extensionId !== extensionId));
+    }
+    #assertReadable() {
+        if (!this.#recoveryComplete) {
+            throw new HostPluginPlatformError('not_ready', 'Plugin Platform is not recovered');
+        }
+        if (this.#phase === 'closed') {
+            throw new HostPluginPlatformError('closed', 'Plugin Platform is closed');
+        }
+    }
+    #assertMutable() {
+        this.#assertReadable();
+        if (this.#phase === 'fenced') {
+            throw new HostPluginPlatformError('recovery_failed', 'Plugin Platform is fenced', {
+                cause: this.#fence,
+            });
+        }
+        if (this.#phase === 'draining') {
+            throw new HostPluginPlatformError('closed', 'Plugin Platform is draining');
+        }
+    }
+    #fenceUnknownPackageOutcome(error, operation) {
+        this.#fence = error;
+        this.#phase = 'fenced';
+        return new HostPluginPlatformError('commit_outcome_unknown', `Plugin package ${operation} outcome is unknown; Plugin Platform was fenced`, { cause: error });
+    }
+    #serializeMutable(operation) {
+        return this.#serialize(async () => {
+            this.#assertMutable();
+            return await operation();
+        });
+    }
+    #serialize(operation) {
+        const result = this.#mutation.then(operation, operation);
+        this.#mutation = result.then(() => undefined, () => undefined);
+        return result;
+    }
+    #recordPackageFailure(extensionId, error) {
+        this.#clearPackageFailure(extensionId);
+        this.#failures = Object.freeze([
+            ...this.#failures,
+            Object.freeze({ extensionId, diagnostic: boundedDiagnostic(error) }),
+        ]);
+    }
+    #settleConvergence(converged) {
+        this.#convergence = converged ? 'converged' : 'diverged';
+        if (!this.#drainRequested && this.#phase !== 'fenced' && this.#phase !== 'closed') {
+            this.#phase = converged ? 'ready' : 'degraded';
+        }
+        if (converged) {
+            this.#reconcileDelayMs = 250;
+            if (this.#reconcileTimer)
+                clearTimeout(this.#reconcileTimer);
+            this.#reconcileTimer = undefined;
+        }
+        else {
+            this.#scheduleReconcile();
+        }
+    }
+    async #reconcileNow() {
+        await this.#packages.recover(this.#authority.generation);
+        await this.#packageLoader.collectGarbage();
+        const projection = await this.#deriveDesired(this.#authority, 'recovery');
+        const packageFailures = [];
+        const retryPackages = new Set(this.#failures.flatMap(({ extensionId }) => (extensionId ? [extensionId] : [])));
+        const storedPackages = new Set(await this.#packages.identities());
+        for (const extensionId of storedPackages) {
+            const installed = this.#composition
+                .installedPackages()
+                .some(({ packageId }) => packageId === extensionId);
+            if (installed && !retryPackages.has(extensionId))
+                continue;
+            try {
+                const loaded = await this.#packageLoader.load(extensionId);
+                await this.#adoptRuntimePackage(extensionId, loaded, projection.desired, installed);
+            }
+            catch (error) {
+                packageFailures.push(Object.freeze({ extensionId, diagnostic: boundedDiagnostic(error) }));
+            }
+        }
+        const runtimeFailures = await this.#recoverDesiredRuntime(projection.desired);
+        this.#desired = projection.desired;
+        this.#structuralDependencies = projection.structuralDependencies;
+        this.#failures = Object.freeze([
+            ...projection.failures,
+            ...packageFailures,
+            ...runtimeFailures.map(({ entryId, diagnostic }) => Object.freeze({ entryId, diagnostic })),
+        ]);
+        this.#settleConvergence(this.#failures.length === 0);
+        return this.#receipt('complete');
+    }
+    #scheduleReconcile() {
+        if (this.#reconcileTimer || this.#drainRequested || this.#phase !== 'degraded')
+            return;
+        const delay = this.#reconcileDelayMs;
+        this.#reconcileDelayMs = Math.min(this.#reconcileDelayMs * 2, 30_000);
+        this.#reconcileTimer = setTimeout(() => {
+            this.#reconcileTimer = undefined;
+            void this.#serialize(async () => {
+                if (this.#phase !== 'degraded')
+                    return;
+                await this.#reconcileNow();
+            }).catch((error) => {
+                this.#composition.root.logger.warn('Unable to reconcile Plugin Platform', error);
+                this.#scheduleReconcile();
+            });
+        }, delay);
+        this.#reconcileTimer.unref?.();
+    }
+    #receipt(cleanup) {
+        return Object.freeze({
+            authorityEpoch: this.#authority.generation,
+            durability: 'committed',
+            convergence: this.#convergence === 'converged' ? 'converged' : 'diverged',
+            cleanup,
+            failures: Object.freeze(this.#failures.map((failure) => Object.freeze({ ...failure }))),
+        });
+    }
+    #structuralDependent(extensionId) {
+        for (const [actor, dependencies] of this.#structuralDependencies) {
+            if (dependencies.has(extensionId))
+                return actor;
+        }
+        return undefined;
+    }
+}
+function emptyCompositionAuthority() {
+    return Object.freeze({
+        schemaVersion: 1,
+        generation: 0,
+        packageLayers: Object.freeze([]),
+        overlays: Object.freeze([]),
+    });
+}
+function emptyCompositionState() {
+    return Object.freeze({
+        schemaVersion: 1,
+        generation: 0,
+        roots: Object.freeze({
+            profile: Object.freeze([]),
+            desktopUi: Object.freeze([]),
+            sessions: Object.freeze({}),
+        }),
+    });
+}
+function compositionAuthority(generation, packageLayers, overlays) {
+    return Object.freeze({
+        schemaVersion: 1,
+        generation,
+        packageLayers: Object.freeze([...packageLayers]),
+        overlays: Object.freeze(structuredClone(overlays)),
+    });
+}
+function compositionEntries(state) {
+    const walk = (entries) => entries.flatMap((entry) => [entry, ...walk(entry.children ?? [])]);
+    return [
+        ...walk(state.roots.profile),
+        ...walk(state.roots.desktopUi),
+        ...Object.values(state.roots.sessions).flatMap(walk),
+    ];
+}
+function findCompositionEntry(state, entryId) {
+    return compositionEntries(state).find((entry) => entry.id === entryId);
+}
+function compositionWithGeneration(state, generation) {
+    return Object.freeze({ ...state, generation });
+}
+function compositionEntryRecords(state) {
+    const records = [];
+    const visit = (entries, rootId, ancestorDisabled) => {
+        for (const entry of entries) {
+            const disabled = ancestorDisabled || entry.disabled === true;
+            records.push(Object.freeze({ entry, rootId, disabled }));
+            visit(entry.children ?? [], rootId, disabled);
+        }
+    };
+    visit(state.roots.profile, 'profile', false);
+    visit(state.roots.desktopUi, 'desktop-ui', false);
+    for (const [scopeId, entries] of Object.entries(state.roots.sessions)) {
+        visit(entries, `session:${scopeId}`, false);
+    }
+    return Object.freeze(records);
+}
+function withoutEntries(state, excluded) {
+    const filter = (entries) => Object.freeze(entries.flatMap((entry) => excluded.has(entry.id)
+        ? []
+        : [Object.freeze({ ...entry, children: filter(entry.children ?? []) })]));
+    return Object.freeze({
+        schemaVersion: 1,
+        generation: state.generation,
+        roots: Object.freeze({
+            profile: filter(state.roots.profile),
+            desktopUi: filter(state.roots.desktopUi),
+            sessions: Object.freeze(Object.fromEntries(Object.entries(state.roots.sessions).map(([scopeId, entries]) => [
+                scopeId,
+                filter(entries),
+            ]))),
+        }),
+    });
+}
+function withoutPackageEntries(state, extensionId) {
+    return withoutEntries(state, new Set(compositionEntries(state)
+        .filter(({ packageId }) => packageId === extensionId)
+        .map(({ id }) => id)));
+}
+function countInspections(inspections) {
+    return inspections.reduce((total, inspection) => total + 1 + countInspections(inspection.children), 0);
+}
+function cloneDependencyGraph(graph) {
+    return new Map([...graph].map(([actor, dependencies]) => [actor, new Set(dependencies)]));
+}
+function freezeDependencyGraph(graph) {
+    return new Map([...graph].map(([actor, dependencies]) => [
+        actor,
+        Object.freeze(new Set([...dependencies].sort())),
+    ]));
+}
+function recordStructuralDependencies(state, owners, dependencies, actor, operation) {
+    const referencedIds = [];
+    if (operation.type === 'insert') {
+        if (operation.parentId)
+            referencedIds.push(operation.parentId);
+    }
+    else {
+        referencedIds.push(operation.entryId);
+        if (operation.type === 'move' && operation.parentId)
+            referencedIds.push(operation.parentId);
+    }
+    for (const entryId of referencedIds) {
+        if (!findCompositionEntry(state, entryId))
+            continue;
+        const owner = owners.get(entryId);
+        if (!owner || owner === actor)
+            continue;
+        const actorDependencies = dependencies.get(actor) ?? new Set();
+        actorDependencies.add(owner);
+        dependencies.set(actor, actorDependencies);
+    }
+}
+function updateEntryOwners(previous, owners, actor, operation) {
+    if (operation.type === 'insert') {
+        for (const entry of walkCompositionEntries(operation.entry))
+            owners.set(entry.id, actor);
+        return;
+    }
+    if (operation.type === 'remove') {
+        const removed = findCompositionEntry(previous, operation.entryId);
+        if (removed) {
+            for (const entry of walkCompositionEntries(removed))
+                owners.delete(entry.id);
+        }
+    }
+}
+function walkCompositionEntries(entry) {
+    return [entry, ...(entry.children ?? []).flatMap(walkCompositionEntries)];
+}
+function overlayFailureIdentity(operations) {
+    const operation = operations[0];
+    if (!operation)
+        return 'user-overlay';
+    if (operation.type === 'insert')
+        return operation.entry.id;
+    return operation.entryId;
+}
+function operationFailures(input, error) {
+    const diagnostic = boundedDiagnostic(error);
+    const ids = new Set();
+    for (const operation of input.operations) {
+        if (operation.type === 'insert')
+            ids.add(operation.entry.id);
+        else
+            ids.add(operation.entryId);
+    }
+    return Object.freeze([...ids].map((entryId) => Object.freeze({ entryId, diagnostic })));
+}
+function scalarConfiguration(value) {
+    if (value === undefined)
+        return Object.freeze({});
+    if (!value || typeof value !== 'object' || Array.isArray(value)) {
+        throw new HostPluginCompositionStoreError('invalid_state', 'Plugin Entry config must be a scalar record');
+    }
+    const output = {};
+    for (const [key, item] of Object.entries(value)) {
+        if (typeof item !== 'string' &&
+            typeof item !== 'boolean' &&
+            !(typeof item === 'number' && Number.isFinite(item))) {
+            throw new HostPluginCompositionStoreError('invalid_state', `Plugin Entry config value is invalid: ${key}`);
+        }
+        output[key] = item;
+    }
+    return Object.freeze(output);
+}
+function asError(error) {
+    return error instanceof Error ? error : new Error(String(error));
+}
+function boundedDiagnostic(error) {
+    const message = error instanceof AggregateError
+        ? error.errors.map((item) => boundedDiagnostic(item)).join('; ')
+        : error instanceof Error
+            ? error.message
+            : String(error);
+    return message.slice(0, 4096) || 'Plugin Platform operation failed';
+}