@zhin.js/runtime 1.0.1 → 1.0.3

package/lib/plugin-scope-assembler.js

@@ -1,25 +1,30 @@
 import { resolve } from 'node:path';
-import { GenerationHandoffStack, Scope, rootPluginId, } from '@zhin.js/plugin-runtime';
+import { GenerationHandoffStack, Scope, capabilityId, featureId, rootPluginId, } from '@zhin.js/plugin-runtime';
 import { runtimeEnvironmentToken } from './environment.js';
 import { EnvStoreFactory, envStoreToken, } from './environment-store.js';
+import { createPrimaryConfig, primaryConfigToken, } from './primary-config.js';
 /** Assembles Plugin setup into mutable shadow maps without publishing them. */
 export class PluginScopeAssembler {
     modules;
     configResolver;
     environment;
+    primaryConfigDocument;
     installResources;
     isolation;
     scopes;
     tree;
     config;
     resources;
+    #setupCapabilities = new Map();
     #created = [];
     #handoffs = new GenerationHandoffStack();
     #envStores;
-    constructor(modules, configResolver, environment, installResources, environmentLayers = {}, seed, isolation) {
+    #setupFeatureAliases = new Map();
+    constructor(modules, configResolver, environment, primaryConfigDocument, installResources, environmentLayers = {}, seed, isolation) {
         this.modules = modules;
         this.configResolver = configResolver;
         this.environment = environment;
+        this.primaryConfigDocument = primaryConfigDocument;
         this.installResources = installResources;
         this.isolation = isolation;
         this.#envStores = new EnvStoreFactory(environment, environmentLayers);
@@ -40,6 +45,9 @@ export class PluginScopeAssembler {
             this.resources.delete(owner);
         }
     }
+    installSetupFeatureAliases(aliases) {
+        this.#setupFeatureAliases = new Map(aliases);
+    }
     async setupTree(node) {
         const manifest = node.package.packageJson.zhin;
         const parentScope = node.parent ? this.scopes.get(node.parent) : undefined;
@@ -49,13 +57,17 @@ export class PluginScopeAssembler {
         this.scopes.set(node.id, scope);
         this.#created.push(node.id);
         // Every owner shadows the inherited EnvStore with its exact overlay view.
-        scope.provide(envStoreToken, this.#envStores.create(node.id));
+        const environment = this.#envStores.create(node.id);
+        scope.provide(envStoreToken, environment);
         if (!node.parent) {
             scope.provide(runtimeEnvironmentToken, this.environment);
+            const config = createPrimaryConfig(this.primaryConfigDocument, environment);
+            scope.provide(primaryConfigToken, config);
             await this.installResources?.({
                 resources: scope,
                 lifecycle: scope.disposers,
                 handoff: this.#handoffs,
+                config,
             });
         }
         const config = Object.freeze(this.configResolver(node) ?? {});
@@ -109,13 +121,33 @@ export class PluginScopeAssembler {
                     throw new Error(`Missing resource ${token.id} for Plugin ${node.id}`);
                 }
             }
-            const returned = await definition.setup?.({
+            const register = (feature, localName, capabilityDefinition) => {
+                const featureName = featureId(String(feature));
+                const id = capabilityId(node.id, featureName, localName);
+                if (this.#setupCapabilities.has(id)) {
+                    throw new Error(`Duplicate setup Capability: ${id}`);
+                }
+                this.#setupCapabilities.set(id, Object.freeze({
+                    id,
+                    owner: node.id,
+                    feature: featureName,
+                    localName,
+                    source: resolve(node.package.root, manifest.entry),
+                    definition: capabilityDefinition,
+                }));
+            };
+            const setupContext = {
                 plugin,
                 config: view,
                 resources: scope,
                 lifecycle: scope.disposers,
                 handoff: this.#handoffs,
-            });
+                addFeature: register,
+            };
+            for (const [method, feature] of this.#setupFeatureAliases) {
+                setupContext[method] = (name, value) => register(feature, name, value);
+            }
+            const returned = await definition.setup?.(Object.freeze(setupContext));
             if (returned)
                 scope.disposers.add(returned);
             metadata = definition.metadata;
@@ -161,6 +193,9 @@ export class PluginScopeAssembler {
     generationHandoff() {
         return this.#handoffs.seal();
     }
+    setupCapabilities() {
+        return Object.freeze([...this.#setupCapabilities.values()]);
+    }
 }
 function isWithin(plugin, root) {
     return plugin === root || plugin.startsWith(`${root}/`);

package/lib/primary-config.d.ts

@@ -0,0 +1,16 @@
+import type { EnvStore } from './environment-store.js';
+import type { RuntimeConfigDocument } from './config-composer.js';
+/**
+ * Generation-owned, validated Root configuration.
+ *
+ * `document` deliberately retains environment placeholders for safe display and
+ * persistence. Runtime consumers use `expanded`, which is derived exclusively
+ * through the Root EnvStore instead of reading process.env themselves.
+ */
+export interface PrimaryConfig {
+    readonly document: RuntimeConfigDocument;
+    readonly expanded: RuntimeConfigDocument;
+    get<T = unknown>(key: string): T | undefined;
+}
+export declare const primaryConfigToken: import("@zhin.js/plugin-runtime").Token<PrimaryConfig>;
+export declare function createPrimaryConfig(document: RuntimeConfigDocument, environment: EnvStore): PrimaryConfig;

package/lib/primary-config.js

@@ -0,0 +1,20 @@
+import { createToken } from '@zhin.js/plugin-runtime';
+export const primaryConfigToken = createToken('zhin.primary-config', 'Validated Root configuration for the current generation');
+export function createPrimaryConfig(document, environment) {
+    const safeDocument = freezeConfig(structuredClone(document));
+    const expanded = freezeConfig(environment.expandMissingAsEmpty(safeDocument));
+    return Object.freeze({
+        document: safeDocument,
+        expanded,
+        get(key) {
+            return expanded[key];
+        },
+    });
+}
+function freezeConfig(value) {
+    if (!value || typeof value !== 'object' || Object.isFrozen(value))
+        return value;
+    for (const child of Object.values(value))
+        freezeConfig(child);
+    return Object.freeze(value);
+}

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';
@@ -118,7 +119,7 @@ export class RootRuntime {
                 restart = new RestartBoundaryPlanner().plan(this.#model.graph, inspected.graph, plan.changed);
                 if (restart)
                     return undefined;
-                prepared = await new TopologyGenerationPreparer(this.#modules, this.#model, inspected.graph, inspected.configResolver, this.#environment, this.#installResources, this.#environmentLayers, this.#isolation).prepare(current);
+                prepared = await new TopologyGenerationPreparer(this.#modules, this.#model, inspected.graph, inspected.configResolver, inspected.primaryConfigDocument, this.#environment, this.#installResources, this.#environmentLayers, this.#isolation).prepare(current);
             }
             else if (plan.subtrees.length === 0 && plan.slots.length > 0 && this.#model) {
                 prepared = await new SlotGenerationPreparer(this.#modules, this.#model)
@@ -168,12 +169,36 @@ export class RootRuntime {
     async #inspectProject() {
         const resolver = await NodePackageResolver.create(this.#projectRoot);
         const graph = await new ProjectGraphService(resolver).inspect(this.#projectRoot);
-        const configResolver = this.#configResolver
-            ? this.#configResolver
-            : await new ConfigComposer()
-                .compose(graph, this.#configDocument)
-                .then((composed) => this.#configViewResolver(composed.views));
-        return { graph, configResolver };
+        await this.#refreshConfigDocument();
+        if (this.#configResolver) {
+            return {
+                graph,
+                configResolver: this.#configResolver,
+                primaryConfigDocument: Object.freeze({}),
+            };
+        }
+        const composed = await new ConfigComposer().compose(graph, this.#configDocument);
+        return {
+            graph,
+            configResolver: this.#configViewResolver(composed.views),
+            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);
@@ -188,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;
@@ -200,33 +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),
-            };
-            if (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)
@@ -237,14 +283,14 @@ export class RootRuntime {
         return snapshot;
     }
     #prepareInspected(current, inspected) {
-        const assembler = new GenerationAssembler(inspected.graph, this.#modules, inspected.configResolver, current.generation + 1, this.#environment, this.#installResources, this.#environmentLayers, this.#isolation);
+        const assembler = new GenerationAssembler(inspected.graph, this.#modules, inspected.configResolver, inspected.primaryConfigDocument, current.generation + 1, this.#environment, this.#installResources, this.#environmentLayers, this.#isolation);
         return assembler.prepare();
     }
     async #prepareSubtrees(current, inspected, roots) {
         if (!this.#model)
             return this.#prepareInspected(current, inspected);
         try {
-            return await new SubtreeGenerationPreparer(this.#modules, this.#model, inspected.graph, inspected.configResolver, this.#environment, this.#installResources, this.#environmentLayers, this.#isolation).prepare(current, roots);
+            return await new SubtreeGenerationPreparer(this.#modules, this.#model, inspected.graph, inspected.configResolver, inspected.primaryConfigDocument, this.#environment, this.#installResources, this.#environmentLayers, this.#isolation).prepare(current, roots);
         }
         catch (error) {
             if (!(error instanceof SubtreeTopologyChangedError))
@@ -278,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) }
@@ -292,6 +343,7 @@ class GenerationAssembler {
     graph;
     modules;
     configResolver;
+    primaryConfigDocument;
     generation;
     environment;
     installResources;
@@ -301,31 +353,35 @@ class GenerationAssembler {
     #catalog = new FeatureCatalog();
     #rootsByFeature = new Map();
     #featureIdsByPackageRoot = new Map();
-    #projectionDisposers = [];
+    #projectionDisposers = new Map();
     #host;
     #plugins;
-    constructor(graph, modules, configResolver, generation, environment, installResources, environmentLayers = {}, isolation) {
+    constructor(graph, modules, configResolver, primaryConfigDocument, generation, environment, installResources, environmentLayers = {}, isolation) {
         this.graph = graph;
         this.modules = modules;
         this.configResolver = configResolver;
+        this.primaryConfigDocument = primaryConfigDocument;
         this.generation = generation;
         this.environment = environment;
         this.installResources = installResources;
         this.environmentLayers = environmentLayers;
         this.isolation = isolation;
         this.#host = new NodeDiscoveryHost(modules);
-        this.#plugins = new PluginScopeAssembler(modules, configResolver, environment, installResources, environmentLayers, undefined, isolation);
+        this.#plugins = new PluginScopeAssembler(modules, configResolver, environment, primaryConfigDocument, installResources, environmentLayers, undefined, isolation);
     }
     async prepare() {
         try {
             // 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);
@@ -351,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;
         }
     }
@@ -378,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;
+}