@zhin.js/runtime 1.1.7 → 1.1.9

package/lib/root-runtime.js

@@ -1,9 +1,10 @@
 import { normalizeSourcePath } from './source-path.js';
 import { resolve } from 'node:path';
 import { isDeepStrictEqual } from 'node:util';
-import { DisposeStack, GenerationHandoffStack, RootController, ConfigDocumentDivergenceError, createSnapshotView, rootPluginId, } from '@zhin.js/plugin-runtime';
+import { DisposeStack, GenerationHandoffStack, RootController, applyConfigPatches, ConfigDocumentDivergenceError, createSnapshotView, rootPluginId, } from '@zhin.js/plugin-runtime';
 import { FeatureCatalog, FeatureDiscovery, } from '@zhin.js/feature-kit';
-import { ConfigComposer } from './config-composer.js';
+import { ConfigComposer, HOST_CONFIG_KEYS } from './config-composer.js';
+import { createPrimaryConfig, primaryConfigToken } from './primary-config.js';
 import { immutableConfigSchema } from './plugin-config-schema.js';
 import { ConfigPatchPlanner } from './config-patch-planner.js';
 import { defineRuntimeEnvironment } from './environment.js';
@@ -25,6 +26,7 @@ import { SubtreeGenerationPreparer, SubtreeTopologyChangedError, } from './subtr
 import { TopologyGenerationPreparer } from './topology-generation-preparer.js';
 import { RestartBoundaryPlanner } from './restart-boundary.js';
 import { RuntimeInputPlanner } from './runtime-input-planner.js';
+import { TopologyTransactionPlanner } from './topology-transaction.js';
 export class RootRuntime {
     #projectRoot;
     #modules;
@@ -38,7 +40,7 @@ export class RootRuntime {
     #configDocument;
     #installResources;
     #isolation;
-    #configPatchTail = Promise.resolve();
+    #controlTail = Promise.resolve();
     #stopResult;
     #initialConfigSchemas = new Map();
     #resolveConfigurationReady;
@@ -56,8 +58,13 @@ export class RootRuntime {
         this.#environment = defineRuntimeEnvironment(options.environment);
         this.#environmentLayers = defineEnvironmentLayers(options.environmentVariables);
         this.#environmentSource = options.environmentSource;
-        if (typeof options.config === 'function')
+        if (options.application !== undefined && typeof options.config !== 'function') {
+            throw new TypeError('application is only used with a custom config resolver; pass the v2 document as config otherwise');
+        }
+        if (typeof options.config === 'function') {
             this.#configResolver = options.config;
+            this.#configDocument = structuredClone(options.application ?? {});
+        }
         else if (isConfigDocumentPort(options.config))
             this.#configPort = options.config;
         else
@@ -94,7 +101,10 @@ export class RootRuntime {
     get sourceOwnership() {
         return this.#controller.committed.state.ownership;
     }
-    async start() {
+    start() {
+        return this.#enqueueControl(() => this.#start());
+    }
+    async #start() {
         try {
             if (this.#environmentSource) {
                 this.#environmentLayers = defineEnvironmentLayers(await this.#environmentSource.read());
@@ -115,15 +125,24 @@ export class RootRuntime {
         }
     }
     async reload(target = rootPluginId()) {
-        const snapshot = await this.#controller.reload(target, async (current, signal) => {
-            return (await this.#prepare(current, signal)).generation;
+        return this.#enqueueControl(async () => {
+            const previousInputs = this.#runtimeInputState();
+            return this.#controller.reload(target, async (current, signal) => {
+                return (await this.#prepare(current, signal)).generation;
+            }).catch(error => {
+                this.#restoreRuntimeInputs(previousInputs);
+                throw error;
+            });
         });
-        return snapshot;
     }
     patchConfig(patches) {
         const operations = cloneConfigPatches(patches);
-        const result = this.#configPatchTail.then(() => this.#applyConfigPatches(operations), () => this.#applyConfigPatches(operations));
-        this.#configPatchTail = result.catch(() => undefined);
+        return this.#enqueueControl(() => this.#applyConfigPatches(operations));
+    }
+    /** Serializes source reads and input adoption around the Controller's generation transaction. */
+    #enqueueControl(operation) {
+        const result = this.#controlTail.then(operation, operation);
+        this.#controlTail = result.catch(() => undefined);
         return result;
     }
     createHmrCoordinator(options) {
@@ -159,10 +178,13 @@ export class RootRuntime {
         return result;
     }
     async #reloadPlan(plan) {
+        return this.#enqueueControl(() => this.#reloadPlanInQueue(plan));
+    }
+    async #reloadPlanInQueue(plan) {
         const inputs = await this.#planRuntimeInputs(plan.changed);
         if (inputs && 'kind' in inputs)
             return inputs;
-        const previousInputs = inputs ? this.#runtimeInputState() : undefined;
+        const previousInputs = this.#runtimeInputState();
         const effectiveInputPlan = inputs
             ? Object.freeze({
                 ...plan,
@@ -179,10 +201,12 @@ export class RootRuntime {
                 && effective.manifestSources.length === 0
                 && effective.subtrees.length === 0
                 && effective.slots.length === 0
-                && resolved.capabilities.size === 0)
+                && resolved.capabilities.size === 0
+                && !inputs.topologyChanged
+                && !inputs.primaryConfigChanged)
                 return undefined;
-            if (this.#model && effective.manifestSources.length > 0) {
-                const inspected = await this.#inspectProject(inputs?.document, inputs?.environmentLayers);
+            if (this.#model && (effective.manifestSources.length > 0 || inputs?.topologyChanged)) {
+                const inspected = inputs?.inspected ?? await this.#inspectProject(inputs?.document, inputs?.environmentLayers);
                 restart = new RestartBoundaryPlanner().plan(this.#model.graph, inspected.graph, effective.changed);
                 if (restart)
                     return undefined;
@@ -191,13 +215,18 @@ export class RootRuntime {
                     : await new TopologyGenerationPreparer(this.#modules, this.#model, inspected.graph, inspected.configResolver, inspected.primaryConfigDocument, this.#environment, this.#installResources, inspected.environmentLayers, this.#isolation).prepare(current, signal, { ...effective, capabilities: resolved.capabilities });
             }
             else if (effective.subtrees.length === 0 && resolved.capabilities.size > 0 && this.#model) {
-                prepared = await new SlotGenerationPreparer(this.#modules, this.#model)
+                prepared = await new SlotGenerationPreparer(this.#modules, this.#model, inputs?.primaryConfigChanged
+                    ? createPrimaryConfig(inputs.inspected.primaryConfigDocument, createEnvStore(rootPluginId(), this.#environment, inputs.environmentLayers), inputs.inspected.configResolver.compositionMode)
+                    : undefined)
                     .prepare(current, resolved.capabilities, signal);
             }
             else if (this.#model && this.#canPrepareSubtrees(effective)) {
-                const inspected = await this.#inspectProject(inputs?.document, inputs?.environmentLayers);
+                const inspected = inputs?.inspected ?? await this.#inspectProject(inputs?.document, inputs?.environmentLayers);
                 prepared = await this.#prepareSubtrees(current, inspected, effective.subtrees, signal);
             }
+            else if (this.#model && inputs?.primaryConfigChanged && effective.subtrees.length === 0 && resolved.capabilities.size === 0) {
+                prepared = await this.#prepareSubtrees(current, inputs.inspected, [], signal);
+            }
             else {
                 prepared = await this.#prepare(current, signal, inputs?.document, inputs?.environmentLayers);
             }
@@ -206,6 +235,9 @@ export class RootRuntime {
             return inputs && previousInputs
                 ? withRuntimeInputHandoff(prepared.generation, () => this.#adoptRuntimeInputs(inputs), () => this.#restoreRuntimeInputs(previousInputs))
                 : prepared.generation;
+        }).catch(error => {
+            this.#restoreRuntimeInputs(previousInputs);
+            throw error;
         });
         if (restart)
             return restart;
@@ -227,8 +259,10 @@ export class RootRuntime {
         const environmentLayers = environmentChanged && this.#environmentSource
             ? defineEnvironmentLayers(await this.#environmentSource.read())
             : this.#environmentLayers;
-        const inputPlan = await new RuntimeInputPlanner(new ConfigComposer(this.#disabledPluginInstanceKeys, this.#modules)).plan({
+        const inspected = await this.#inspectProject(document, environmentLayers, configSnapshot?.pluginOrder ?? this.#configSnapshot?.pluginOrder);
+        const inputPlan = await new RuntimeInputPlanner(new ConfigComposer(this.#disabledPluginInstanceKeys, this.#modules), this.#committedConfigComposer()).plan({
             graph: this.#model.graph,
+            nextGraph: inspected.graph,
             environment: this.#environment,
             previousDocument: requireConfigDocument(this.#configDocument),
             nextDocument: document,
@@ -248,6 +282,9 @@ export class RootRuntime {
             environmentLayers,
             inputSources,
             roots: inputPlan.roots,
+            inspected,
+            topologyChanged: new TopologyTransactionPlanner().plan(this.#model.graph, inspected.graph).changed,
+            primaryConfigChanged: this.#primaryConfigChanged(inspected.primaryConfigDocument),
         });
     }
     #adoptRuntimeInputs(candidate) {
@@ -303,14 +340,14 @@ export class RootRuntime {
         signal.throwIfAborted();
         return this.#prepareInspected(current, inspected, signal);
     }
-    async #inspectProject(document, environmentLayers = this.#environmentLayers) {
-        const resolver = await NodePackageResolver.create(this.#projectRoot);
-        const graph = await new ProjectGraphService(resolver, {
-            disabledPluginInstanceKeys: this.#disabledPluginInstanceKeys,
-        }).inspect(this.#projectRoot);
+    async #inspectProject(document, environmentLayers = this.#environmentLayers, pluginOrder) {
         if (document === undefined)
             await this.#refreshConfigDocument();
         const activeDocument = document ?? this.#configDocument;
+        const resolver = await NodePackageResolver.create(this.#projectRoot);
+        const graph = await new ProjectGraphService(resolver, {
+            disabledPluginInstanceKeys: this.#disabledPluginInstanceKeys,
+        }).inspect(this.#projectRoot, activeDocument, pluginOrder ?? this.#configSnapshot?.pluginOrder);
         if (this.#configResolver) {
             const customResolver = this.#configResolver;
             const schemas = new Map(graphNodes(graph.root).flatMap(node => {
@@ -319,6 +356,7 @@ export class RootRuntime {
             }));
             const configResolver = node => customResolver(node);
             configResolver.schema = node => schemas.get(node.id);
+            configResolver.compositionMode = 'custom';
             if (this.snapshot.generation === 0) {
                 this.#initialConfigSchemas = new Map(graphNodes(graph.root).flatMap(node => {
                     const schema = schemas.get(node.id);
@@ -329,7 +367,7 @@ export class RootRuntime {
             return {
                 graph,
                 configResolver,
-                primaryConfigDocument: Object.freeze({}),
+                primaryConfigDocument: Object.freeze(structuredClone(activeDocument ?? {})),
                 environmentLayers,
             };
         }
@@ -374,14 +412,26 @@ export class RootRuntime {
                 .expandMissingAsEmpty(view);
         };
         resolver.schema = (node) => schemas?.get(node.id);
+        resolver.compositionMode = 'document';
         return resolver;
     }
+    #committedConfigComposer() {
+        return new ConfigComposer([], undefined, new Map([...this.snapshot.tree.values()].flatMap(node => node.configSchema ? [[node.id, node.configSchema]] : [])));
+    }
+    #committedPrimaryConfig() {
+        return this.snapshot.resources.get(rootPluginId())?.get(primaryConfigToken.id);
+    }
+    #primaryConfigChanged(document) {
+        return !isDeepStrictEqual(this.#committedPrimaryConfig()?.document, document);
+    }
     async #applyConfigPatches(patches) {
-        if (!this.#configDocument) {
+        if (this.#configResolver || !this.#configDocument) {
             throw new Error('Config patches require a document-backed RootRuntime config');
         }
         // Adopt any external edit before planning so the port's revision check
         // cannot conflict and the patch applies on top of the on-disk document.
+        const previousInputs = this.#runtimeInputState();
+        const previousDocument = this.#configDocument;
         await this.#refreshConfigDocument();
         const currentDocument = requireConfigDocument(this.#configDocument);
         let plan;
@@ -390,31 +440,34 @@ export class RootRuntime {
         const snapshot = await this.#controller.reload(rootPluginId(), async (current, signal) => {
             let prepared;
             signal.throwIfAborted();
-            const resolver = await NodePackageResolver.create(this.#projectRoot);
-            const graph = await new ProjectGraphService(resolver, {
-                disabledPluginInstanceKeys: this.#disabledPluginInstanceKeys,
-            }).inspect(this.#projectRoot);
-            const planned = await new ConfigPatchPlanner(new ConfigComposer(this.#disabledPluginInstanceKeys, this.#modules)).plan(graph, currentDocument, patches);
-            plan = planned;
-            if (!planned.documentChanged)
-                return undefined;
             try {
-                if (this.#configPort) {
+                const candidate = applyConfigPatches(currentDocument, patches);
+                const editsDeclarations = patches.some(patch => patch.path.length === 0 || patch.path[0] === 'plugins');
+                if (this.#configPort && (!isDeepStrictEqual(currentDocument, candidate) || editsDeclarations)) {
                     const currentSnapshot = requireConfigDocumentSnapshot(this.#configSnapshot);
                     // Port preparation must remain inert; validation and shadow setup can
                     // still reject this candidate without touching the backing document.
                     documentTransaction = await this.#configPort.prepare(currentSnapshot, patches);
-                    if (!isDeepStrictEqual(documentTransaction.document, planned.candidate)) {
+                    if (!isDeepStrictEqual(documentTransaction.document, candidate)) {
                         throw new ConfigDocumentDivergenceError();
                     }
                 }
-                // Host-level sections (http/database/ai/...) never land in a Plugin
-                // view, so their patches plan zero roots. With a Root Resource
-                // installer the whole generation must still be rebuilt; only an
-                // installer-less runtime may take the commit-only shortcut.
-                if (!this.#installResources && planned.roots.length === 0) {
+                const resolver = await NodePackageResolver.create(this.#projectRoot);
+                const graphService = new ProjectGraphService(resolver, {
+                    disabledPluginInstanceKeys: this.#disabledPluginInstanceKeys,
+                });
+                const previousGraph = this.#model?.graph ?? await graphService.inspect(this.#projectRoot, previousDocument);
+                const pluginOrder = documentTransaction?.pluginOrder
+                    ?? patchedPluginOrder(this.#configSnapshot?.pluginOrder, candidate, patches);
+                const graph = await graphService.inspect(this.#projectRoot, candidate, pluginOrder);
+                const planned = await new ConfigPatchPlanner(new ConfigComposer(this.#disabledPluginInstanceKeys, this.#modules), this.#committedConfigComposer()).plan(previousGraph, currentDocument, patches, graph, previousDocument);
+                plan = planned;
+                const topologyChanged = this.#model
+                    ? new TopologyTransactionPlanner().plan(this.#model.graph, graph).changed : false;
+                const orderChanged = !isDeepStrictEqual(this.#configSnapshot?.pluginOrder, pluginOrder);
+                if (!planned.documentChanged && !topologyChanged && !orderChanged && isDeepStrictEqual(previousDocument, candidate)) {
                     if (documentTransaction)
-                        committedDocument = await documentTransaction.commit();
+                        await documentTransaction.rollback();
                     return undefined;
                 }
                 const inspected = {
@@ -423,15 +476,30 @@ export class RootRuntime {
                     primaryConfigDocument: planned.document,
                     environmentLayers: this.#environmentLayers,
                 };
-                // Root resources may consume any Primary Config section. Reinstall them
-                // when present so a committed patch cannot leave Host services on the
-                // previous generation's document.
-                if (this.#model && !planned.roots.includes(rootPluginId()) && planned.roots.length > 0) {
+                if (!this.#primaryConfigChanged(planned.document) && planned.roots.length === 0 && !topologyChanged) {
+                    if (documentTransaction)
+                        committedDocument = await documentTransaction.commit();
+                    return undefined;
+                }
+                const previousPrimary = this.#committedPrimaryConfig()?.document;
+                const hostChanged = HOST_CONFIG_KEYS.some(key => !isDeepStrictEqual(previousPrimary?.[key], planned.document[key]));
+                const retainRoot = !this.#installResources || !hostChanged;
+                // Host sections require resource reinstallation. Other edits publish a
+                // current PrimaryConfig projection while retaining Root lifetimes.
+                if (this.#model && retainRoot && topologyChanged && !planned.roots.includes(rootPluginId())) {
+                    prepared = await new TopologyGenerationPreparer(this.#modules, this.#model, graph, inspected.configResolver, inspected.primaryConfigDocument, this.#environment, this.#installResources, this.#environmentLayers, this.#isolation).prepare(current, signal);
+                }
+                else if (this.#model && retainRoot && !planned.roots.includes(rootPluginId())) {
                     prepared = await this.#prepareSubtrees(current, inspected, planned.roots, signal);
                 }
                 else {
                     prepared = await this.#prepareInspected(current, inspected, signal);
                 }
+                if (!prepared) {
+                    if (documentTransaction)
+                        committedDocument = await documentTransaction.commit();
+                    return undefined;
+                }
                 return documentTransaction
                     ? withConfigDocumentHandoff(prepared.generation, documentTransaction, (committed) => { committedDocument = committed; })
                     : prepared.generation;
@@ -444,6 +512,9 @@ export class RootRuntime {
                     await documentTransaction.rollback().catch(() => undefined);
                 throw error;
             }
+        }).catch(error => {
+            this.#restoreRuntimeInputs(previousInputs);
+            throw error;
         });
         const completed = requireConfigPatchPlan(plan);
         this.#configDocument = completed.candidate;
@@ -472,6 +543,29 @@ function collapseInvalidationSubtrees(values) {
     const sorted = [...new Set(values)].sort((left, right) => left.length - right.length);
     return Object.freeze(sorted.filter((candidate, index) => !sorted.slice(0, index).some((root) => isWithinInvalidationRoot(candidate, root))));
 }
+/** Preserve known source ordering when a structural port omits optional write metadata. */
+function patchedPluginOrder(previous, candidate, patches) {
+    if (!previous)
+        return undefined;
+    let order = [...previous];
+    for (const patch of patches) {
+        if (patch.path.length === 0 || (patch.path[0] === 'plugins' && patch.path.length === 1)) {
+            const value = patch.path.length === 0 && patch.op === 'set'
+                ? patch.value?.plugins : patch.op === 'set' ? patch.value : {};
+            order = value && typeof value === 'object' ? Object.keys(value) : [];
+        }
+        else if (patch.path[0] === 'plugins' && patch.path[1]) {
+            const key = patch.path[1];
+            if (patch.op === 'remove')
+                order = order.filter(alias => alias !== key);
+            else if (!order.includes(key))
+                order.push(key);
+        }
+    }
+    const plugins = candidate.plugins;
+    const keys = plugins && typeof plugins === 'object' ? Object.keys(plugins) : [];
+    return Object.freeze([...order.filter(key => keys.includes(key)), ...keys.filter(key => !order.includes(key))]);
+}
 function isWithinInvalidationRoot(plugin, root) {
     return plugin === root || plugin.startsWith(`${root}/`);
 }

package/lib/runtime-input-planner.d.ts

@@ -12,9 +12,11 @@ export interface RuntimeInputPlan {
 /** Classifies config/environment changes by their actual expanded runtime projection. */
 export declare class RuntimeInputPlanner {
     private readonly composer;
-    constructor(composer?: ConfigComposer);
+    private readonly previousComposer;
+    constructor(composer?: ConfigComposer, previousComposer?: ConfigComposer);
     plan(options: {
         readonly graph: ProjectGraph;
+        readonly nextGraph?: ProjectGraph;
         readonly environment: RuntimeEnvironment;
         readonly previousDocument: RuntimeConfigDocument;
         readonly nextDocument: RuntimeConfigDocument;

package/lib/runtime-input-planner.js

@@ -5,15 +5,18 @@ import { createEnvStore, } from './environment-store.js';
 /** Classifies config/environment changes by their actual expanded runtime projection. */
 export class RuntimeInputPlanner {
     composer;
-    constructor(composer = new ConfigComposer()) {
+    previousComposer;
+    constructor(composer = new ConfigComposer(), previousComposer = composer) {
         this.composer = composer;
+        this.previousComposer = previousComposer;
     }
     async plan(options) {
-        const previous = await this.composer.compose(options.graph, options.previousDocument);
-        const next = await this.composer.compose(options.graph, options.nextDocument);
+        const previous = await this.previousComposer.compose(options.graph, options.previousDocument);
+        const nextGraph = options.nextGraph ?? options.graph;
+        const next = await this.composer.compose(nextGraph, options.nextDocument);
         const environmentChanged = !isDeepStrictEqual(options.previousEnvironment, options.nextEnvironment);
         const hostKeys = HOST_CONFIG_KEYS.filter((key) => !isDeepStrictEqual(expandHostValue(previous.document[key], options.environment, options.previousEnvironment), expandHostValue(next.document[key], options.environment, options.nextEnvironment)));
-        const changed = indexGraph(options.graph)
+        const changed = indexGraph(nextGraph)
             .filter((node) => !isDeepStrictEqual(expandPluginView(node.id, previous.views.get(node.id), options.environment, options.previousEnvironment), expandPluginView(node.id, next.views.get(node.id), options.environment, options.nextEnvironment)))
             .map((node) => node.id);
         // EnvStore is itself a public Plugin resource. A changed global layer can

package/lib/slot-generation-preparer.d.ts

@@ -1,10 +1,12 @@
 import { type CapabilityId, type RuntimeSnapshot } from '@zhin.js/plugin-runtime';
 import type { ModuleRuntime } from './module-runtime.js';
 import { type PreparedRuntimeGeneration, type RuntimeGenerationModel } from './runtime-generation.js';
+import { type PrimaryConfig } from './primary-config.js';
 import { type CapabilityDelta } from './convention-capability-delta.js';
 export declare class SlotGenerationPreparer {
     private readonly modules;
     private readonly model;
-    constructor(modules: ModuleRuntime, model: RuntimeGenerationModel);
+    private readonly primaryConfig?;
+    constructor(modules: ModuleRuntime, model: RuntimeGenerationModel, primaryConfig?: PrimaryConfig | undefined);
     prepare(current: RuntimeSnapshot, selected: readonly CapabilityId[] | CapabilityDelta, signal: AbortSignal): Promise<PreparedRuntimeGeneration>;
 }

package/lib/slot-generation-preparer.js

@@ -4,13 +4,16 @@ import { FeatureProjector, composeGenerationHandoffs } from './feature-projector
 import { NodeDiscoveryHost } from './node-discovery-host.js';
 import { prepareRuntimeGeneration, } from './runtime-generation.js';
 import { SourceOwnershipIndex } from './source-ownership.js';
+import { projectPrimaryConfigResources } from './primary-config.js';
 import { capabilityDeltaFromSlots, } from './convention-capability-delta.js';
 export class SlotGenerationPreparer {
     modules;
     model;
-    constructor(modules, model) {
+    primaryConfig;
+    constructor(modules, model, primaryConfig) {
         this.modules = modules;
         this.model = model;
+        this.primaryConfig = primaryConfig;
     }
     async prepare(current, selected, signal) {
         signal.throwIfAborted();
@@ -38,7 +41,9 @@ export class SlotGenerationPreparer {
             root: current.root,
             tree: current.tree,
             config: current.config,
-            resources: current.resources,
+            resources: this.primaryConfig
+                ? projectPrimaryConfigResources(current.resources, this.primaryConfig)
+                : current.resources,
             capabilities,
         }, signal, current.projections);
         try {

package/lib/topology-generation-preparer.js

@@ -78,13 +78,19 @@ export class TopologyGenerationPreparer {
             plugins.synchronizeTree(this.graph.root);
             const capabilities = await this.#prepareCapabilities(current, plan, setupRoots, featureTopology, selected);
             mergeSetupCapabilities(capabilities, plugins.setupCapabilities(), featureTopology.providers, featureTopology.rootsByFeature);
-            const projected = await new FeatureProjector(featureTopology.providers.values()).project(current.generation + 1, {
+            const providers = [...featureTopology.providers.values()].filter(provider => provider.runtime.retain !== 'when-owner-unchanged'
+                || this.model.providers.get(provider.id) !== provider
+                || !current.projections.has(provider.id)
+                || !sameFeatureOwners(this.model.rootsByFeature.get(provider.id) ?? [], featureTopology.rootsByFeature.get(provider.id) ?? [], this.model.scopes, plugins.scopes)
+                || !sameFeatureSlots(provider.id, current.capabilities, capabilities));
+            const retained = new Map([...current.projections].filter(([id]) => featureTopology.providers.has(id)));
+            const projected = await new FeatureProjector(providers).project(current.generation + 1, {
                 root: current.root,
                 tree: plugins.tree,
                 config: plugins.config,
                 resources: plugins.resources,
                 capabilities,
-            }, signal);
+            }, signal, retained);
             for (const [feature, dispose] of projected.disposers) {
                 projectionDisposers.set(feature, dispose);
             }
@@ -92,7 +98,10 @@ export class TopologyGenerationPreparer {
             plugins.bindCandidateSnapshot(snapshot);
             const ownership = SourceOwnershipIndex.fromGeneration(this.graph, snapshot, featureTopology.featureIdsByPackageRoot);
             const replacements = new Map(plugins.createdScopeDisposers());
-            const assets = this.model.assets.replaceScopes(graphOrder(this.graph), replacements, new Set([...this.model.providers.keys(), ...featureTopology.providers.keys()]), projectionDisposers);
+            const assets = this.model.assets.replaceScopes(graphOrder(this.graph), replacements, new Set([
+                ...providers.map(provider => provider.id),
+                ...[...this.model.providers.keys()].filter(id => !featureTopology.providers.has(id)),
+            ]), projectionDisposers);
             return prepareRuntimeGeneration({
                 snapshot: projected.state,
                 dispose: () => assets.dispose(),
@@ -276,6 +285,19 @@ function selectedSlotsByFeature(current, selected, refreshed) {
 function sameValues(left, right) {
     return left.length === right.length && left.every((value, index) => value === right[index]);
 }
+function sameFeatureSlots(feature, previous, next) {
+    const before = [...previous.values()].filter(slot => slot.feature === feature);
+    const after = [...next.values()].filter(slot => slot.feature === feature);
+    return before.length === after.length && before.every(slot => next.get(slot.id) === slot);
+}
+function sameFeatureOwners(previous, next, previousScopes, nextScopes) {
+    return previous.length === next.length && previous.every((root, index) => {
+        const candidate = next[index];
+        return candidate?.owner === root.owner
+            && candidate.packageRoot === root.packageRoot
+            && previousScopes.get(root.owner) === nextScopes.get(root.owner);
+    });
+}
 async function rollback(scopeDisposers, projectionDisposers, prepareError) {
     const disposers = new DisposeStack();
     for (const dispose of scopeDisposers)

package/lib/topology-transaction.js

@@ -1,4 +1,5 @@
 import { resolve } from 'node:path';
+import { isDeepStrictEqual } from 'node:util';
 /** Compiles two resolved graphs into the smallest safe topology transaction. */
 export class TopologyTransactionPlanner {
     plan(previous, next) {
@@ -90,7 +91,8 @@ function scopeContractChanged(previous, next) {
         || previous.package.name !== next.package.name
         || previousManifest.entry !== nextManifest.entry
         || previousManifest.runtime !== nextManifest.runtime
-        || previousManifest.engine !== nextManifest.engine);
+        || previousManifest.engine !== nextManifest.engine
+        || !isDeepStrictEqual(previousManifest.metadata, nextManifest.metadata));
 }
 function childOrderChanged(previous, next) {
     for (const [id, node] of next) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhin.js/runtime",
-  "version": "1.1.7",
+  "version": "1.1.9",
   "description": "Static Plugin graph, generation transaction and HMR Root runtime for Zhin.js",
   "type": "module",
   "main": "./lib/index.js",
@@ -19,25 +19,25 @@
     "es-module-lexer": "2.3.1",
     "import-meta-resolve": "4.2.0",
     "semver": "7.8.5",
-    "@zhin.js/feature-kit": "1.1.5",
-    "@zhin.js/plugin-runtime": "1.1.14"
+    "@zhin.js/feature-kit": "1.1.6",
+    "@zhin.js/plugin-runtime": "1.1.15"
   },
   "devDependencies": {
     "@types/node": "^26.1.2",
     "tsx": "^4.23.1",
     "typescript": "^6.0.3",
-    "@zhin.js/agent-feature": "1.1.6",
-    "@zhin.js/command": "1.1.7",
-    "@zhin.js/adapter": "1.1.19",
-    "@zhin.js/component": "1.1.6",
-    "@zhin.js/handler": "1.1.5",
-    "@zhin.js/layout": "1.1.6",
-    "@zhin.js/mcp-feature": "1.1.6",
-    "@zhin.js/middleware": "1.1.6",
-    "@zhin.js/page": "1.1.6",
-    "@zhin.js/prompt-section": "1.1.5",
-    "@zhin.js/skill": "1.1.6",
-    "@zhin.js/tool": "1.1.6"
+    "@zhin.js/adapter": "1.1.20",
+    "@zhin.js/command": "1.1.8",
+    "@zhin.js/component": "1.1.7",
+    "@zhin.js/handler": "1.1.6",
+    "@zhin.js/mcp-feature": "1.1.7",
+    "@zhin.js/agent-feature": "1.1.7",
+    "@zhin.js/page": "1.1.7",
+    "@zhin.js/prompt-section": "1.1.6",
+    "@zhin.js/skill": "1.1.7",
+    "@zhin.js/tool": "1.1.7",
+    "@zhin.js/middleware": "1.1.7",
+    "@zhin.js/layout": "1.1.7"
   },
   "repository": {
     "type": "git",