@zhin.js/runtime 1.0.2 → 1.0.3

package/lib/project-graph.d.ts

@@ -18,13 +18,14 @@ export interface ProjectGraph {
     readonly packages: ReadonlyMap<string, ResolvedPackage>;
     readonly buildOrder: readonly ResolvedPackage[];
 }
+export interface ProjectGraphServiceOptions {
+    readonly engineVersion?: string;
+}
 export declare class ProjectGraphError extends Error {
     constructor(message: string);
 }
 export declare class ProjectGraphService {
     #private;
-    private readonly resolver;
-    private readonly engineVersion;
-    constructor(resolver: PackageResolver, engineVersion?: string);
+    constructor(resolver: PackageResolver, engineVersionOrOptions?: string | ProjectGraphServiceOptions);
     inspect(projectRoot: string): Promise<ProjectGraph>;
 }

package/lib/project-graph.js

@@ -1,6 +1,7 @@
 import { childPluginId, rootPluginId } from '@zhin.js/plugin-runtime';
 import { assertFeatureApi, assertPackageEngine, runtimeEngineVersion, } from './compatibility.js';
 import { PackageResolutionError, } from './package-resolver.js';
+import { PLATFORM_FEATURE_CARRIER, PLATFORM_FEATURE_FACADE, declaredPackageDependency, mergeChildPluginReferences, mergeFeatureReferences, } from './platform-features.js';
 export class ProjectGraphError extends Error {
     constructor(message) {
         super(message);
@@ -8,18 +9,20 @@ export class ProjectGraphError extends Error {
     }
 }
 export class ProjectGraphService {
-    resolver;
-    engineVersion;
-    constructor(resolver, engineVersion = runtimeEngineVersion) {
-        this.resolver = resolver;
-        this.engineVersion = engineVersion;
+    #resolver;
+    #engineVersion;
+    constructor(resolver, engineVersionOrOptions = runtimeEngineVersion) {
+        this.#resolver = resolver;
+        this.#engineVersion = typeof engineVersionOrOptions === 'string'
+            ? engineVersionOrOptions
+            : (engineVersionOrOptions.engineVersion ?? runtimeEngineVersion);
     }
     async inspect(projectRoot) {
-        const rootPackage = await this.resolver.root(projectRoot);
+        const rootPackage = await this.#resolver.root(projectRoot);
         assertPackageType(rootPackage, 'plugin');
         const packages = new Map();
-        const root = await this.#visitPlugin(rootPackage, rootPluginId(), 'root', undefined, [], packages);
-        for (const pkg of this.resolver.workspacePackages())
+        const root = await this.#visitPlugin(rootPackage, rootPluginId(), 'root', undefined, [], packages, true);
+        for (const pkg of this.#resolver.workspacePackages())
             addPackage(packages, pkg);
         return Object.freeze({
             root,
@@ -27,39 +30,62 @@ export class ProjectGraphService {
             buildOrder: topologicalBuildOrder(packages),
         });
     }
-    async #visitPlugin(pkg, id, instanceKey, parent, ancestors, packages) {
+    async #visitPlugin(pkg, id, instanceKey, parent, ancestors, packages, isRoot) {
         if (ancestors.includes(pkg.root)) {
             throw new ProjectGraphError(`Plugin cycle detected: ${[...ancestors, pkg.root].join(' -> ')}`);
         }
         const manifest = assertPackageType(pkg, 'plugin');
-        assertPackageEngine(pkg, this.engineVersion);
+        assertPackageEngine(pkg, this.#engineVersion);
         addPackage(packages, pkg);
+        let featureCarrier;
+        let pluginFacade;
+        let featureRefs = manifest.features;
+        let pluginRefs = manifest.plugins;
+        if (isRoot && manifest.platformFeatures !== false) {
+            const platform = await tryResolvePlatform(this.#resolver, pkg);
+            featureCarrier = platform.featureCarrier;
+            pluginFacade = platform.pluginFacade;
+            if (featureCarrier) {
+                addPackage(packages, featureCarrier);
+                const carrierManifest = featureCarrier.packageJson.zhin;
+                const inherited = carrierManifest.type === 'plugin' ? carrierManifest.features : [];
+                featureRefs = mergeFeatureReferences(manifest.features, inherited);
+            }
+            if (pluginFacade) {
+                addPackage(packages, pluginFacade);
+                const facadeManifest = pluginFacade.packageJson.zhin;
+                const inheritedPlugins = facadeManifest.type === 'plugin' ? facadeManifest.plugins : [];
+                pluginRefs = mergeChildPluginReferences(manifest.plugins, inheritedPlugins);
+            }
+        }
         const featurePackages = new Set();
-        const features = await Promise.all(manifest.features.map(async (reference) => {
+        const features = await Promise.all(featureRefs.map(async (reference) => {
             if (featurePackages.has(reference.package)) {
                 throw new ProjectGraphError(`Duplicate Feature requirement ${reference.package} in ${pkg.name}`);
             }
             featurePackages.add(reference.package);
-            const resolved = await resolveReference(this.resolver, pkg, reference);
+            const resolved = await this.#resolveFeatureReference(pkg, reference, featureCarrier);
             if (!resolved)
                 return undefined;
             assertPackageType(resolved, 'feature');
-            assertPackageEngine(resolved, this.engineVersion);
+            assertPackageEngine(resolved, this.#engineVersion);
             assertFeatureApi(pkg, reference, resolved);
             addPackage(packages, resolved);
             return Object.freeze({ reference, package: resolved });
         }));
+        const ownPluginKeys = new Set(manifest.plugins.map((item) => item.instanceKey));
         const instanceKeys = new Set();
-        const children = await Promise.all(manifest.plugins.map(async (reference) => {
+        const children = await Promise.all(pluginRefs.map(async (reference) => {
             if (instanceKeys.has(reference.instanceKey)) {
                 throw new ProjectGraphError(`Duplicate child instanceKey ${reference.instanceKey} in ${pkg.name}`);
             }
             instanceKeys.add(reference.instanceKey);
-            const resolved = await resolveReference(this.resolver, pkg, reference);
+            const resolveFrom = ownPluginKeys.has(reference.instanceKey) ? pkg : (pluginFacade ?? pkg);
+            const resolved = await resolveReference(this.#resolver, resolveFrom, reference);
             if (!resolved)
                 return undefined;
             assertPackageType(resolved, 'plugin');
-            return this.#visitPlugin(resolved, childPluginId(id, reference.instanceKey), reference.instanceKey, id, [...ancestors, pkg.root], packages);
+            return this.#visitPlugin(resolved, childPluginId(id, reference.instanceKey), reference.instanceKey, id, [...ancestors, pkg.root], packages, false);
         }));
         return Object.freeze({
             id,
@@ -70,15 +96,62 @@ export class ProjectGraphService {
             children: Object.freeze(children.filter(isDefined)),
         });
     }
+    async #resolveFeatureReference(pkg, reference, featureCarrier) {
+        try {
+            return await this.#resolver.resolve(reference.package, pkg);
+        }
+        catch (error) {
+            // 非解析类错误（损坏的 package.json 等）不回退、不容错，直接上抛。
+            if (!(error instanceof PackageResolutionError))
+                throw error;
+            // carrier 回退：继承自 @zhin.js/core 的 Feature 引用声明在 carrier 上，
+            // 从引用包解析失败（未声明 / 未安装 / workspace 链接缺失）时改从 carrier 解析。
+            if (featureCarrier)
+                return resolveReference(this.#resolver, featureCarrier, reference);
+            // 无 carrier 时按统一规则处理：optional 引用容错，其余上抛。
+            if (reference.optional)
+                return undefined;
+            throw error;
+        }
+    }
+}
+async function tryResolvePlatform(resolver, from) {
+    let featureCarrier;
+    let pluginFacade;
+    const directCore = declaredPackageDependency(from.packageJson.dependencies, from.packageJson.optionalDependencies, PLATFORM_FEATURE_CARRIER);
+    if (directCore) {
+        try {
+            featureCarrier = await resolver.resolve(PLATFORM_FEATURE_CARRIER, from);
+        }
+        catch (error) {
+            if (!(error instanceof PackageResolutionError))
+                throw error;
+        }
+    }
+    const facadeDecl = declaredPackageDependency(from.packageJson.dependencies, from.packageJson.optionalDependencies, PLATFORM_FEATURE_FACADE);
+    if (facadeDecl) {
+        try {
+            pluginFacade = await resolver.resolve(PLATFORM_FEATURE_FACADE, from);
+            if (!featureCarrier) {
+                featureCarrier = await resolver.resolve(PLATFORM_FEATURE_CARRIER, pluginFacade);
+            }
+        }
+        catch (error) {
+            if (!(error instanceof PackageResolutionError))
+                throw error;
+            pluginFacade = undefined;
+        }
+    }
+    return { featureCarrier, pluginFacade };
 }
 async function resolveReference(resolver, from, reference) {
     try {
         return await resolver.resolve(reference.package, from);
     }
     catch (error) {
-        if (reference.optional
-            && error instanceof PackageResolutionError
-            && error.message.startsWith('Cannot resolve'))
+        // optional 引用对所有 PackageResolutionError 统一容错（未声明 / 未安装 /
+        // workspace 链接缺失）；非解析类错误（损坏的 package.json 等）继续上抛。
+        if (reference.optional && error instanceof PackageResolutionError)
             return undefined;
         throw error;
     }

package/lib/root-runtime.js

@@ -12,11 +12,12 @@ import { GenerationAssets } from './generation-assets.js';
 import { NodeDiscoveryHost } from './node-discovery-host.js';
 import { NodePackageResolver } from './package-resolver.js';
 import { PluginScopeAssembler, } from './plugin-scope-assembler.js';
-import { ProjectGraphService } from './project-graph.js';
+import { ProjectGraphService, } from './project-graph.js';
 import { HmrCoordinator } from './hmr-coordinator.js';
 import { RootProcessRestartExecutor, } from './process-restart.js';
 import { SlotGenerationPreparer } from './slot-generation-preparer.js';
 import { SourceOwnershipIndex } from './source-ownership.js';
+import { addCapabilitySlot, featureSetupAliases, mergeSetupCapabilities, } from './setup-capabilities.js';
 import { SubtreeGenerationPreparer, SubtreeTopologyChangedError, } from './subtree-generation-preparer.js';
 import { TopologyGenerationPreparer } from './topology-generation-preparer.js';
 import { RestartBoundaryPlanner } from './restart-boundary.js';
@@ -168,6 +169,7 @@ export class RootRuntime {
     async #inspectProject() {
         const resolver = await NodePackageResolver.create(this.#projectRoot);
         const graph = await new ProjectGraphService(resolver).inspect(this.#projectRoot);
+        await this.#refreshConfigDocument();
         if (this.#configResolver) {
             return {
                 graph,
@@ -182,6 +184,22 @@ export class RootRuntime {
             primaryConfigDocument: composed.document,
         };
     }
+    /**
+     * The config file itself is watched, so an external edit triggers a full
+     * reload. Re-read through the port before composing: without this the reload
+     * would rebuild the whole generation from the stale in-memory document read
+     * at start, the edit would silently not apply, and the next patchConfig
+     * would hit a revision conflict. On drift the file is authoritative.
+     */
+    async #refreshConfigDocument() {
+        if (!this.#configPort)
+            return;
+        const snapshot = await this.#configPort.read();
+        if (snapshot.revision === this.#configSnapshot?.revision)
+            return;
+        this.#configSnapshot = snapshot;
+        this.#configDocument = structuredClone(snapshot.document);
+    }
     #configViewResolver(views) {
         const env = createEnvStore(rootPluginId(), this.#environment, this.#environmentLayers);
         return (node) => {
@@ -195,7 +213,10 @@ export class RootRuntime {
         if (!this.#configDocument) {
             throw new Error('Config patches require a document-backed RootRuntime config');
         }
-        const currentDocument = this.#configDocument;
+        // 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.
+        await this.#refreshConfigDocument();
+        const currentDocument = requireConfigDocument(this.#configDocument);
         let plan;
         let prepared;
         let documentTransaction;
@@ -207,37 +228,51 @@ export class RootRuntime {
             plan = planned;
             if (!planned.documentChanged)
                 return undefined;
-            if (this.#configPort) {
-                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)) {
-                    throw new ConfigDocumentDivergenceError();
+            try {
+                if (this.#configPort) {
+                    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)) {
+                        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) {
+                    if (documentTransaction)
+                        committedDocument = await documentTransaction.commit();
+                    return undefined;
+                }
+                const inspected = {
+                    graph,
+                    configResolver: this.#configViewResolver(planned.views),
+                    primaryConfigDocument: planned.document,
+                };
+                // 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.#installResources && this.#model && !planned.roots.includes(rootPluginId())) {
+                    prepared = await this.#prepareSubtrees(current, inspected, planned.roots);
                 }
+                else {
+                    prepared = await this.#prepareInspected(current, inspected);
+                }
+                return documentTransaction
+                    ? withConfigDocumentHandoff(prepared.generation, documentTransaction, (committed) => { committedDocument = committed; })
+                    : prepared.generation;
             }
-            if (planned.roots.length === 0) {
+            catch (error) {
+                // A prepared document transaction is inert until handoff; roll it back
+                // before any shadow-phase failure escapes so the port never leaks a
+                // pending write.
                 if (documentTransaction)
-                    committedDocument = await documentTransaction.commit();
-                return undefined;
-            }
-            const inspected = {
-                graph,
-                configResolver: this.#configViewResolver(planned.views),
-                primaryConfigDocument: planned.document,
-            };
-            // 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.#installResources && this.#model && !planned.roots.includes(rootPluginId())) {
-                prepared = await this.#prepareSubtrees(current, inspected, planned.roots);
-            }
-            else {
-                prepared = await this.#prepareInspected(current, inspected);
+                    await documentTransaction.rollback().catch(() => undefined);
+                throw error;
             }
-            return documentTransaction
-                ? withConfigDocumentHandoff(prepared.generation, documentTransaction, (committed) => { committedDocument = committed; })
-                : prepared.generation;
         });
         const completed = requireConfigPatchPlan(plan);
         if (prepared)
@@ -289,6 +324,11 @@ function requireConfigDocumentSnapshot(snapshot) {
         throw new Error('ConfigDocumentPort has not been read');
     return snapshot;
 }
+function requireConfigDocument(document) {
+    if (!document)
+        throw new Error('Config patches require a document-backed RootRuntime config');
+    return document;
+}
 function cloneConfigPatches(patches) {
     return Object.freeze(patches.map((patch) => Object.freeze(patch.op === 'set'
         ? { ...patch, path: Object.freeze([...patch.path]), value: structuredClone(patch.value) }
@@ -313,7 +353,7 @@ class GenerationAssembler {
     #catalog = new FeatureCatalog();
     #rootsByFeature = new Map();
     #featureIdsByPackageRoot = new Map();
-    #projectionDisposers = [];
+    #projectionDisposers = new Map();
     #host;
     #plugins;
     constructor(graph, modules, configResolver, primaryConfigDocument, generation, environment, installResources, environmentLayers = {}, isolation) {
@@ -334,11 +374,14 @@ class GenerationAssembler {
             // Prepare is deliberately ordered: providers define discovery, setup
             // creates owner scopes, then definitions can be projected against both.
             await this.#loadProviders(this.graph.root);
+            this.#plugins.installSetupFeatureAliases(featureSetupAliases(this.#catalog.values()));
             await this.#plugins.setupTree(this.graph.root);
             await this.#discover();
             const projected = await new FeatureProjector(this.#catalog.values())
                 .project(this.generation, this.#projectionState());
-            this.#projectionDisposers.push(...projected.disposers);
+            for (const [feature, dispose] of projected.disposers) {
+                this.#projectionDisposers.set(feature, dispose);
+            }
             const state = projected.state;
             const snapshot = createSnapshotView(this.generation, state);
             const ownership = SourceOwnershipIndex.fromGeneration(this.graph, snapshot, this.#featureIdsByPackageRoot);
@@ -364,7 +407,7 @@ class GenerationAssembler {
             };
         }
         catch (error) {
-            await disposePreparedParts(this.#plugins.createdScopeDisposers().map(([, dispose]) => dispose), this.#projectionDisposers, error);
+            await disposePreparedParts(this.#plugins.createdScopeDisposers().map(([, dispose]) => dispose), [...this.#projectionDisposers.values()], error);
             throw error;
         }
     }
@@ -391,12 +434,13 @@ class GenerationAssembler {
             await this.#loadProviders(child);
     }
     async #discover() {
+        mergeSetupCapabilities(this.#capabilities, this.#plugins.setupCapabilities(), new Map(this.#catalog.values().map((provider) => [provider.id, provider])), this.#rootsByFeature);
         const discovery = new FeatureDiscovery(this.#host);
         for (const provider of this.#catalog.values()) {
             const roots = this.#rootsByFeature.get(provider.id) ?? [];
             const slots = await discovery.discover(provider, roots);
             for (const slot of slots)
-                this.#capabilities.set(slot.id, slot);
+                addCapabilitySlot(this.#capabilities, slot);
         }
     }
     #projectionState() {

package/lib/setup-capabilities.d.ts

@@ -0,0 +1,5 @@
+import { type CapabilityId, type CapabilitySlot, type FeatureId, type SetupCapabilityRegistration } from '@zhin.js/plugin-runtime';
+import type { CapabilityRoot, FeatureProvider } from '@zhin.js/feature-kit';
+export declare function mergeSetupCapabilities(capabilities: Map<CapabilityId, CapabilitySlot>, registrations: readonly Readonly<SetupCapabilityRegistration>[], providers: ReadonlyMap<FeatureId, FeatureProvider>, rootsByFeature: ReadonlyMap<FeatureId, readonly CapabilityRoot[]>): void;
+export declare function addCapabilitySlot(capabilities: Map<CapabilityId, CapabilitySlot>, slot: Readonly<CapabilitySlot>): void;
+export declare function featureSetupAliases(providers: Iterable<FeatureProvider>): ReadonlyMap<string, FeatureId>;

package/lib/setup-capabilities.js

@@ -0,0 +1,44 @@
+import { createCapabilitySlot, } from '@zhin.js/plugin-runtime';
+export function mergeSetupCapabilities(capabilities, registrations, providers, rootsByFeature) {
+    for (const registration of registrations) {
+        const provider = providers.get(registration.feature);
+        const mounted = rootsByFeature.get(registration.feature)?.some((root) => root.owner === registration.owner);
+        if (!provider || !mounted) {
+            throw new Error(`Feature ${registration.feature} is not mounted for Plugin ${registration.owner}`);
+        }
+        const definition = provider.authoring.validate(registration.definition, {
+            owner: registration.owner,
+            feature: registration.feature,
+            localName: registration.localName,
+            source: registration.source,
+        });
+        addCapabilitySlot(capabilities, createCapabilitySlot({
+            owner: registration.owner,
+            feature: registration.feature,
+            localName: registration.localName,
+            source: registration.source,
+            definition,
+            origin: 'setup',
+        }));
+    }
+}
+export function addCapabilitySlot(capabilities, slot) {
+    if (capabilities.has(slot.id)) {
+        throw new Error(`Duplicate Capability Slot: ${slot.id}`);
+    }
+    capabilities.set(slot.id, slot);
+}
+export function featureSetupAliases(providers) {
+    const aliases = new Map();
+    for (const provider of providers) {
+        const method = provider.authoring.setupMethod;
+        if (!method)
+            continue;
+        const existing = aliases.get(method);
+        if (existing && existing !== provider.id) {
+            throw new Error(`Duplicate Feature setup method ${method}: ${existing}, ${provider.id}`);
+        }
+        aliases.set(method, provider.id);
+    }
+    return aliases;
+}

package/lib/slot-generation-preparer.js

@@ -24,17 +24,25 @@ export class SlotGenerationPreparer {
             for (const slot of replacements)
                 capabilities.set(slot.id, slot);
         }
-        const projected = await new FeatureProjector(this.model.providers.values()).project(current.generation + 1, {
+        // Capability-file HMR projects only the owning Features. The complete
+        // snapshot below is assembled by retaining every other projection.
+        const providers = [...selectedByFeature.keys()].map((feature) => {
+            const provider = this.model.providers.get(feature);
+            if (!provider)
+                throw new Error(`Missing Feature provider for ${feature}`);
+            return provider;
+        });
+        const projected = await new FeatureProjector(providers).project(current.generation + 1, {
             root: current.root,
             tree: current.tree,
             config: current.config,
             resources: current.resources,
             capabilities,
-        });
+        }, current.projections);
         try {
             const snapshot = createSnapshotView(current.generation + 1, projected.state);
             const ownership = SourceOwnershipIndex.fromGeneration(this.model.graph, snapshot, this.model.featureIdsByPackageRoot);
-            const assets = this.model.assets.fork(projected.disposers);
+            const assets = this.model.assets.replaceProjections(selectedByFeature.keys(), projected.disposers);
             return {
                 generation: {
                     snapshot: projected.state,
@@ -46,7 +54,7 @@ export class SlotGenerationPreparer {
             };
         }
         catch (error) {
-            await disposeProjections(projected.disposers, error);
+            await disposeProjections(projected.disposers.values(), error);
             throw error;
         }
     }

package/lib/source-ownership.js

@@ -42,6 +42,8 @@ export class SourceOwnershipIndex {
             }
         });
         for (const slot of snapshot.capabilities.values()) {
+            if (slot.origin === 'setup')
+                continue;
             index.add({
                 source: slot.source,
                 role: 'capability',

package/lib/subtree-generation-preparer.js

@@ -4,6 +4,7 @@ import { FeatureProjector, composeGenerationHandoffs } from './feature-projector
 import { NodeDiscoveryHost } from './node-discovery-host.js';
 import { PluginScopeAssembler, } from './plugin-scope-assembler.js';
 import { SourceOwnershipIndex } from './source-ownership.js';
+import { addCapabilitySlot, featureSetupAliases, mergeSetupCapabilities, } from './setup-capabilities.js';
 export class SubtreeTopologyChangedError extends Error {
     constructor(message) {
         super(message);
@@ -41,8 +42,9 @@ export class SubtreeGenerationPreparer {
             config: current.config,
             resources: current.resources,
         }, this.isolation);
+        plugins.installSetupFeatureAliases(featureSetupAliases(this.model.providers.values()));
         plugins.removeSubtrees(roots);
-        const projectionDisposers = [];
+        const projectionDisposers = new Map();
         try {
             for (const root of roots) {
                 const node = nodes.get(root);
@@ -55,6 +57,7 @@ export class SubtreeGenerationPreparer {
                 if (roots.some((root) => isWithin(slot.owner, root)))
                     capabilities.delete(id);
             }
+            mergeSetupCapabilities(capabilities, plugins.setupCapabilities(), this.model.providers, this.model.rootsByFeature);
             const discovery = new FeatureDiscovery(new NodeDiscoveryHost(this.modules));
             for (const provider of this.model.providers.values()) {
                 const affectedRoots = (this.model.rootsByFeature.get(provider.id) ?? [])
@@ -63,7 +66,7 @@ export class SubtreeGenerationPreparer {
                     continue;
                 const slots = await discovery.discover(provider, affectedRoots);
                 for (const slot of slots)
-                    capabilities.set(slot.id, slot);
+                    addCapabilitySlot(capabilities, slot);
             }
             const projected = await new FeatureProjector(this.model.providers.values()).project(current.generation + 1, {
                 root: current.root,
@@ -72,7 +75,9 @@ export class SubtreeGenerationPreparer {
                 resources: plugins.resources,
                 capabilities,
             });
-            projectionDisposers.push(...projected.disposers);
+            for (const [feature, dispose] of projected.disposers) {
+                projectionDisposers.set(feature, dispose);
+            }
             const snapshot = createSnapshotView(current.generation + 1, projected.state);
             const ownership = SourceOwnershipIndex.fromGeneration(this.graph, snapshot, this.model.featureIdsByPackageRoot);
             const replacements = new Map(plugins.createdScopeDisposers());
@@ -95,7 +100,7 @@ export class SubtreeGenerationPreparer {
             };
         }
         catch (error) {
-            await rollback(plugins.createdScopeDisposers().map(([, dispose]) => dispose), projectionDisposers, error);
+            await rollback(plugins.createdScopeDisposers().map(([, dispose]) => dispose), [...projectionDisposers.values()], error);
             throw error;
         }
     }

package/lib/topology-generation-preparer.js

@@ -6,6 +6,7 @@ import { FeatureProjector, composeGenerationHandoffs } from './feature-projector
 import { NodeDiscoveryHost } from './node-discovery-host.js';
 import { PluginScopeAssembler, } from './plugin-scope-assembler.js';
 import { SourceOwnershipIndex } from './source-ownership.js';
+import { addCapabilitySlot, featureSetupAliases, mergeSetupCapabilities, } from './setup-capabilities.js';
 import { TopologyTransactionPlanner, collapseRoots, graphNodes, graphOrder, isWithin, } from './topology-transaction.js';
 /** Prepares manifest topology changes without rebuilding stable Plugin Scopes. */
 export class TopologyGenerationPreparer {
@@ -47,6 +48,7 @@ export class TopologyGenerationPreparer {
             config: current.config,
             resources: current.resources,
         }, this.isolation);
+        plugins.installSetupFeatureAliases(featureSetupAliases(featureTopology.providers.values()));
         const setupRoots = collapseRoots([
             ...plan.addedPluginRoots,
             ...plan.replacedPluginRoots,
@@ -56,7 +58,7 @@ export class TopologyGenerationPreparer {
             ...plan.replacedPluginRoots,
         ]);
         plugins.removeSubtrees(removalRoots);
-        const projectionDisposers = [];
+        const projectionDisposers = new Map();
         try {
             for (const root of setupRoots) {
                 const node = nextNodes.get(root);
@@ -68,6 +70,7 @@ export class TopologyGenerationPreparer {
             // remove, move, or reorder operations.
             plugins.synchronizeTree(this.graph.root);
             const capabilities = await this.#prepareCapabilities(current, plan, setupRoots, featureTopology);
+            mergeSetupCapabilities(capabilities, plugins.setupCapabilities(), featureTopology.providers, featureTopology.rootsByFeature);
             const projected = await new FeatureProjector(featureTopology.providers.values()).project(current.generation + 1, {
                 root: current.root,
                 tree: plugins.tree,
@@ -75,7 +78,9 @@ export class TopologyGenerationPreparer {
                 resources: plugins.resources,
                 capabilities,
             });
-            projectionDisposers.push(...projected.disposers);
+            for (const [feature, dispose] of projected.disposers) {
+                projectionDisposers.set(feature, dispose);
+            }
             const snapshot = createSnapshotView(current.generation + 1, projected.state);
             const ownership = SourceOwnershipIndex.fromGeneration(this.graph, snapshot, featureTopology.featureIdsByPackageRoot);
             const replacements = new Map(plugins.createdScopeDisposers());
@@ -98,7 +103,7 @@ export class TopologyGenerationPreparer {
             };
         }
         catch (error) {
-            await rollback(plugins.createdScopeDisposers().map(([, dispose]) => dispose), projectionDisposers, error);
+            await rollback(plugins.createdScopeDisposers().map(([, dispose]) => dispose), [...projectionDisposers.values()], error);
             throw error;
         }
     }
@@ -177,7 +182,7 @@ export class TopologyGenerationPreparer {
             if (!provider)
                 throw new Error(`Missing Feature provider for ${feature}`);
             for (const slot of await discovery.discover(provider, selected)) {
-                capabilities.set(slot.id, slot);
+                addCapabilitySlot(capabilities, slot);
             }
         }
         return capabilities;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhin.js/runtime",
-  "version": "1.0.2",
+  "version": "1.0.3",
   "description": "Static Plugin graph, generation transaction and HMR Root runtime for Zhin.js",
   "type": "module",
   "main": "./lib/index.js",
@@ -18,22 +18,22 @@
   "dependencies": {
     "ajv": "8.18.0",
     "semver": "7.8.5",
-    "@zhin.js/feature-kit": "1.0.2",
-    "@zhin.js/plugin-runtime": "1.1.0"
+    "@zhin.js/feature-kit": "1.0.3",
+    "@zhin.js/plugin-runtime": "1.1.1"
   },
   "devDependencies": {
     "@types/node": "^26.1.0",
     "typescript": "^6.0.3",
-    "@zhin.js/adapter": "1.1.0",
-    "@zhin.js/command": "1.0.2",
-    "@zhin.js/agent-feature": "1.0.2",
-    "@zhin.js/component": "1.0.2",
-    "@zhin.js/layout": "1.0.2",
-    "@zhin.js/mcp-feature": "1.0.2",
-    "@zhin.js/middleware": "1.0.2",
-    "@zhin.js/tool": "1.0.2",
-    "@zhin.js/page": "1.0.2",
-    "@zhin.js/skill": "1.0.2"
+    "@zhin.js/adapter": "1.1.1",
+    "@zhin.js/agent-feature": "1.0.3",
+    "@zhin.js/command": "1.0.3",
+    "@zhin.js/component": "1.0.3",
+    "@zhin.js/layout": "1.0.3",
+    "@zhin.js/mcp-feature": "1.0.3",
+    "@zhin.js/middleware": "1.0.3",
+    "@zhin.js/page": "1.0.3",
+    "@zhin.js/skill": "1.0.3",
+    "@zhin.js/tool": "1.0.3"
   },
   "repository": {
     "type": "git",