@zhin.js/runtime 1.1.8 → 1.1.10

package/lib/index.d.ts

@@ -1,4 +1,5 @@
 export * from './config-composer.js';
+export * from './application-plugin-declaration.js';
 export { readPluginConfigSchema } from './plugin-config-schema.js';
 export * from './config-patch-planner.js';
 export * from './package-contract.js';

package/lib/index.js

@@ -1,4 +1,5 @@
 export * from './config-composer.js';
+export * from './application-plugin-declaration.js';
 export { readPluginConfigSchema } from './plugin-config-schema.js';
 export * from './config-patch-planner.js';
 export * from './package-contract.js';

package/lib/manifest.d.ts

@@ -12,6 +12,10 @@ export interface ZhinPluginManifest {
     readonly entry: string;
     readonly engine?: string;
     readonly runtime?: 'trusted' | 'isolated';
+    readonly metadata?: Readonly<{
+        displayName?: string;
+        icon?: string;
+    }>;
     /**
      * When true (default), Root plugins receive official Stable Features
      * (`@zhin.js/adapter|command|component`) from the platform/CLI even if they
@@ -49,3 +53,13 @@ export declare class ManifestValidationError extends Error {
     constructor(issues: readonly string[]);
 }
 export declare function parsePackageJson(value: unknown, source: string): PackageJson;
+/** Conditions tried, in order, when `exports["./zhin"]` is a condition object. */
+export declare const ZHIN_EXPORT_CONDITIONS: readonly ["zhin", "import", "default"];
+/**
+ * The runtime entry declared by `exports["./zhin"]`, if any.
+ *
+ * A string target is used as is; a condition object is searched for `zhin`, then `import`,
+ * then `default` (nested condition objects are searched the same way); an array uses its
+ * first target that resolves. Other conditions such as `types` or `require` are ignored.
+ */
+export declare function zhinExportTarget(packageExports: unknown): string | undefined;

package/lib/manifest.js

@@ -12,7 +12,7 @@ export function parsePackageJson(value, source) {
     const name = readString(record, 'name', source, issues);
     if (name && !isPackageName(name))
         issues.push(`${source}#name is not a valid package name`);
-    const zhin = parseZhinManifest(record.zhin, `${source}#zhin`, issues);
+    const zhin = parseZhinManifest(record.zhin, `${source}#zhin`, issues, record.exports, `${source}#exports`);
     const version = optionalString(record.version, `${source}#version`, issues);
     const moduleType = optionalModuleType(record.type, `${source}#type`, issues);
     const main = optionalString(record.main, `${source}#main`, issues);
@@ -42,12 +42,54 @@ export function parsePackageJson(value, source) {
         zhin,
     });
 }
-function parseZhinManifest(value, source, issues) {
+/** Conditions tried, in order, when `exports["./zhin"]` is a condition object. */
+export const ZHIN_EXPORT_CONDITIONS = Object.freeze(['zhin', 'import', 'default']);
+/**
+ * The runtime entry declared by `exports["./zhin"]`, if any.
+ *
+ * A string target is used as is; a condition object is searched for `zhin`, then `import`,
+ * then `default` (nested condition objects are searched the same way); an array uses its
+ * first target that resolves. Other conditions such as `types` or `require` are ignored.
+ */
+export function zhinExportTarget(packageExports) {
+    if (!packageExports || typeof packageExports !== 'object' || Array.isArray(packageExports))
+        return undefined;
+    if (!Object.hasOwn(packageExports, './zhin'))
+        return undefined;
+    return selectExportTarget(packageExports['./zhin']);
+}
+function selectExportTarget(value) {
+    if (typeof value === 'string')
+        return value;
+    if (Array.isArray(value)) {
+        for (const item of value) {
+            const target = selectExportTarget(item);
+            if (target !== undefined)
+                return target;
+        }
+        return undefined;
+    }
+    if (!value || typeof value !== 'object')
+        return undefined;
+    for (const condition of ZHIN_EXPORT_CONDITIONS) {
+        if (!Object.hasOwn(value, condition))
+            continue;
+        const target = selectExportTarget(value[condition]);
+        if (target !== undefined)
+            return target;
+    }
+    return undefined;
+}
+function parseZhinManifest(value, source, issues, packageExports, exportsSource = 'exports') {
     const record = asRecord(value, source, issues);
     if (record.protocol !== 1)
         issues.push(`${source}.protocol must be 1`);
     const type = readString(record, 'type', source, issues);
-    const entry = readRelativeEntry(record.entry, `${source}.entry`, issues);
+    // `zhin.entry` wins when present; `exports["./zhin"]` is the standard-field alternative.
+    const exportedEntry = record.entry === undefined ? zhinExportTarget(packageExports) : undefined;
+    const entry = exportedEntry !== undefined
+        ? readRelativeEntry(exportedEntry, `${exportsSource}["./zhin"]`, issues)
+        : readRelativeEntry(record.entry, `${source}.entry`, issues, `${exportsSource}["./zhin"]`);
     const engine = optionalString(record.engine, `${source}.engine`, issues);
     if (!entry || (type !== 'plugin' && type !== 'feature')) {
         if (type && type !== 'plugin' && type !== 'feature') {
@@ -75,11 +117,25 @@ function parseZhinManifest(value, source, issues) {
         entry,
         engine,
         runtime: runtime,
+        metadata: parsePluginMetadata(record.metadata, `${source}.metadata`, issues),
         platformFeatures,
         features: parseReferences(record.features, `${source}.features`, issues, false),
         plugins: parseReferences(record.plugins, `${source}.plugins`, issues, true),
     });
 }
+function parsePluginMetadata(value, source, issues) {
+    if (value === undefined)
+        return undefined;
+    const record = asRecord(value, source, issues);
+    for (const key of Object.keys(record)) {
+        if (key !== 'displayName' && key !== 'icon')
+            issues.push(`${source}.${key} is not supported`);
+    }
+    return Object.freeze({
+        ...(record.displayName !== undefined ? { displayName: readString(record, 'displayName', source, issues) } : {}),
+        ...(record.icon !== undefined ? { icon: readString(record, 'icon', source, issues) } : {}),
+    });
+}
 function parseReferences(value, source, issues, child) {
     if (value === undefined)
         return [];
@@ -118,7 +174,11 @@ function parseReferences(value, source, issues, child) {
             }];
     });
 }
-function readRelativeEntry(value, source, issues) {
+function readRelativeEntry(value, source, issues, alternative) {
+    if (value === undefined && alternative) {
+        issues.push(`${source} or ${alternative} must declare a package-relative path starting with ./`);
+        return undefined;
+    }
     if (typeof value !== 'string' || !value.startsWith('./')) {
         issues.push(`${source} must be a package-relative path starting with ./`);
         return undefined;

package/lib/native-development-runtime.js

@@ -4,6 +4,7 @@ import { basename, extname, isAbsolute, relative, resolve, sep } from 'node:path
 import { pathToFileURL } from 'node:url';
 import { ModuleDependencyIndex, } from './module-dependency-index.js';
 import { withToolPackageInstallHint } from './missing-tool-package.js';
+import { isEditorTempFile } from './editor-temp-file.js';
 import { ensureTypeScriptSpecifierRemap } from './typescript-specifier-remap.js';
 const ignoredDirectories = new Set([
     '.git', '.zhin', 'coverage', 'data', 'dist', 'lib', 'node_modules',
@@ -353,8 +354,12 @@ function sourceSnapshot(roots) {
         visit(root);
     return result;
 }
+/** Shared by the native watcher and the polling fallback, so both skip the same files. */
 function isWatchedSource(source) {
     const name = source.slice(source.lastIndexOf(sep) + 1);
+    // Editor temp/backup files (e.g. `.!97910!index.ts`, `.env.swp`) never reload (#857).
+    if (isEditorTempFile(name))
+        return false;
     return watchedExtensions.has(extname(source)) || name.startsWith('.env');
 }
 /** Mirrors sourceSnapshot: any path segment matching an ignored directory opts out. */

package/lib/plugin-config-schema.d.ts

@@ -4,3 +4,13 @@ import type { ResolvedPackage } from './package-resolver.js';
 export declare function readPluginConfigSchema(pkg: ResolvedPackage, modules?: Pick<ModuleRuntime, 'load'>): Promise<Readonly<Record<string, unknown>> | null>;
 /** Detached declaration metadata for preflight and custom-resolver startup views. */
 export declare function immutableConfigSchema(schema: Readonly<Record<string, unknown>>): Readonly<Record<string, unknown>>;
+/**
+ * Thrown when a trusted plugin declares both `definePlugin({ config })` and a root `schema.json`.
+ * Neither source wins: startup stops so the two schemas cannot silently drift apart.
+ */
+export declare class PluginConfigSourceConflictError extends TypeError {
+    readonly packageName: string;
+    readonly entryFile: string;
+    readonly schemaFile: string;
+    constructor(packageName: string, entryFile: string, schemaFile: string);
+}

package/lib/plugin-config-schema.js

@@ -14,12 +14,14 @@ export async function readPluginConfigSchema(pkg, modules) {
     // Isolated plugin code never executes in the composition process.
     const manifest = pkg.packageJson.zhin;
     let declaration;
+    let entryFile;
     if (modules && manifest.type === 'plugin' && manifest.runtime !== 'isolated') {
-        const module = await modules.load(resolve(pkg.root, manifest.entry));
+        entryFile = resolve(pkg.root, manifest.entry);
+        const module = await modules.load(entryFile);
         declaration = module.default?.config;
     }
     if (declaration && fileSchema !== undefined) {
-        throw new TypeError(`${pkg.name} declares both plugin config and schema.json; choose one configuration schema`);
+        throw new PluginConfigSourceConflictError(pkg.name, entryFile ?? manifest.entry, file);
     }
     const schema = declaration ? declaration.toJsonSchema() : fileSchema;
     if (schema === undefined)
@@ -42,3 +44,24 @@ export function immutableConfigSchema(schema) {
     freeze(copy);
     return copy;
 }
+/**
+ * Thrown when a trusted plugin declares both `definePlugin({ config })` and a root `schema.json`.
+ * Neither source wins: startup stops so the two schemas cannot silently drift apart.
+ */
+export class PluginConfigSourceConflictError extends TypeError {
+    packageName;
+    entryFile;
+    schemaFile;
+    constructor(packageName, entryFile, schemaFile) {
+        super(`${packageName} declares both plugin config and schema.json; choose one configuration schema. `
+            + `Inline config: definePlugin({ config }) in ${entryFile}. JSON Schema: ${schemaFile}. `
+            + 'Zhin does not pick one for you. To keep the typed inline Schema, delete schema.json; '
+            + 'to keep schema.json (required for isolated plugins, readable without running the plugin), '
+            + 'remove config from definePlugin. '
+            + 'See https://zhin.js.org/authoring/define-plugin#choose-a-config-source');
+        this.packageName = packageName;
+        this.entryFile = entryFile;
+        this.schemaFile = schemaFile;
+        this.name = 'PluginConfigSourceConflictError';
+    }
+}

package/lib/plugin-scope-assembler.d.ts

@@ -1,14 +1,15 @@
-import { DisposeStack, Scope, type Dispose, type FeatureId, type GenerationHandoff, type GenerationAdmissionGate, type GenerationHandoffRegistry, type RuntimeSnapshot, type PluginId, type PluginNodeSnapshot, type SetupCapabilityRegistration, type TokenId } from '@zhin.js/plugin-runtime';
+import { DisposeStack, Scope, type Dispose, type FeatureId, type GenerationHandoff, type GenerationAdmissionGate, type GenerationHandoffRegistry, type RuntimeSnapshot, type RuntimeConfigDocument, type PluginId, type PluginNodeSnapshot, type SetupCapabilityRegistration, type TokenId } from '@zhin.js/plugin-runtime';
 import { type RuntimeEnvironment } from './environment.js';
 import { type EnvironmentLayers } from './environment-store.js';
 import type { ModuleRuntime } from './module-runtime.js';
 import type { PluginGraphNode } from './project-graph.js';
 import type { IsolatedPluginRuntimePort } from './isolation.js';
 import { type PrimaryConfig } from './primary-config.js';
-import type { RuntimeConfigDocument } from '@zhin.js/plugin-runtime';
 export interface PluginConfigResolver {
     (node: PluginGraphNode): unknown;
     schema?(node: PluginGraphNode): Readonly<Record<string, unknown>> | undefined;
+    /** Set by RootRuntime's actual composition branch, not by Plugin config values. */
+    compositionMode?: NonNullable<PrimaryConfig['compositionMode']>;
 }
 export interface RootResourceContext {
     /** Exact shadow generation being assembled; never inferred from a latest snapshot. */
@@ -42,7 +43,6 @@ export declare class PluginScopeAssembler {
     private readonly modules;
     private readonly configResolver;
     private readonly environment;
-    private readonly primaryConfigDocument;
     private readonly generation;
     private readonly installResources?;
     private readonly isolation?;

package/lib/plugin-scope-assembler.js

@@ -2,13 +2,12 @@ import { resolve } from 'node:path';
 import { GenerationHandoffStack, Scope, capabilityId, createGenerationAdmissionGate, createToken, PluginDatabaseHost, PluginOutboundHost, PluginScheduleHost, databaseHostToken, databaseRootHostToken, outboundHostToken, outboundRootHostToken, featureId, rootPluginId, scheduleHostToken, scheduleRootHostToken, } from '@zhin.js/plugin-runtime';
 import { runtimeEnvironmentToken } from './environment.js';
 import { EnvStoreFactory, envStoreToken, } from './environment-store.js';
-import { createPrimaryConfig, primaryConfigToken, } from './primary-config.js';
+import { createPrimaryConfig, projectPrimaryConfigResources, primaryConfigToken, } from './primary-config.js';
 /** Assembles Plugin setup into mutable shadow maps without publishing them. */
 export class PluginScopeAssembler {
     modules;
     configResolver;
     environment;
-    primaryConfigDocument;
     generation;
     installResources;
     isolation;
@@ -22,20 +21,21 @@ export class PluginScopeAssembler {
     #admission = createGenerationAdmissionGate();
     #envStores;
     #candidateSnapshot;
+    #primaryConfig;
     #setupFeatureAliases = new Map();
     constructor(modules, configResolver, environment, primaryConfigDocument, generation, installResources, environmentLayers = {}, seed, isolation) {
         this.modules = modules;
         this.configResolver = configResolver;
         this.environment = environment;
-        this.primaryConfigDocument = primaryConfigDocument;
         this.generation = generation;
         this.installResources = installResources;
         this.isolation = isolation;
         this.#envStores = new EnvStoreFactory(environment, environmentLayers);
+        this.#primaryConfig = createPrimaryConfig(primaryConfigDocument, this.#envStores.create(rootPluginId()), configResolver.compositionMode);
         this.scopes = new Map(seed?.scopes);
         this.tree = new Map(seed?.tree);
         this.config = new Map(seed?.config);
-        this.resources = new Map(seed?.resources);
+        this.resources = projectPrimaryConfigResources(seed?.resources ?? new Map(), this.#primaryConfig);
     }
     removeSubtrees(roots) {
         // Seeded Scopes belong to a committed generation. Removing a map entry
@@ -64,12 +64,14 @@ export class PluginScopeAssembler {
         // Every owner shadows the inherited EnvStore with its exact overlay view.
         const environment = this.#envStores.create(node.id);
         scope.provide(envStoreToken, environment);
+        // New setup operations shadow a retained parent's construction-time value;
+        // operation contexts read the immutable projection from their own snapshot.
+        scope.provide(primaryConfigToken, this.#primaryConfig);
         const register = (feature, localName, capabilityDefinition) => this.#registerSetupCapability(node, manifest, feature, localName, capabilityDefinition);
         if (!node.parent) {
             scope.provide(runtimeEnvironmentToken, this.environment);
             scope.provide(rootGenerationAdmissionToken, this.#admission);
-            const config = createPrimaryConfig(this.primaryConfigDocument, environment);
-            scope.provide(primaryConfigToken, config);
+            const config = this.#primaryConfig;
             await this.installResources?.({
                 generation: this.generation,
                 readCandidateSnapshot: () => {
@@ -130,7 +132,7 @@ export class PluginScopeAssembler {
             }
             if (prepared.handoff)
                 this.#handoffs.add(prepared.handoff);
-            metadata = prepared.descriptor.metadata;
+            metadata = mergePluginMetadata(manifest, prepared.descriptor.metadata, node.id);
         }
         else {
             const module = await this.modules.load(resolve(node.package.root, manifest.entry));
@@ -139,6 +141,7 @@ export class PluginScopeAssembler {
             if (!definition || typeof definition.name !== 'string') {
                 throw new TypeError(`${node.package.name} does not default-export a Plugin definition`);
             }
+            metadata = mergePluginMetadata(manifest, definition.metadata, node.id);
             for (const token of definition.requires ?? []) {
                 if (!scope.has(token)) {
                     throw new Error(`Missing resource ${token.id} for Plugin ${node.id}`);
@@ -160,7 +163,6 @@ export class PluginScopeAssembler {
             signal.throwIfAborted();
             if (returned)
                 scope.disposers.add(returned);
-            metadata = definition.metadata;
         }
         scope.seal();
         this.tree.set(node.id, Object.freeze({
@@ -257,3 +259,11 @@ const rootGenerationAdmissionToken = createToken('zhin.runtime.root-generation-a
 function isWithin(plugin, root) {
     return plugin === root || plugin.startsWith(`${root}/`);
 }
+function mergePluginMetadata(manifest, code, owner) {
+    for (const key of ['displayName', 'icon']) {
+        if (manifest.metadata?.[key] !== undefined && code?.[key] !== undefined) {
+            throw new TypeError(`Plugin ${owner} declares metadata.${key} in both manifest and code`);
+        }
+    }
+    return manifest.metadata || code ? Object.freeze({ ...code, ...manifest.metadata }) : undefined;
+}

package/lib/primary-config.d.ts

@@ -1,5 +1,5 @@
+import { type PluginId, type RuntimeConfigDocument, type SnapshotState, type TokenId } from '@zhin.js/plugin-runtime';
 import type { EnvStore } from './environment-store.js';
-import type { RuntimeConfigDocument } from '@zhin.js/plugin-runtime';
 /**
  * Generation-owned, validated Root configuration.
  *
@@ -8,9 +8,13 @@ import type { RuntimeConfigDocument } from '@zhin.js/plugin-runtime';
  * through the Root EnvStore instead of reading process.env themselves.
  */
 export interface PrimaryConfig {
+    /** Actual Runtime composition branch; absent on older authorities, never inferred from values. */
+    readonly compositionMode?: 'document' | 'custom' | 'unknown';
     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;
+export declare function createPrimaryConfig(document: RuntimeConfigDocument, environment: EnvStore, compositionMode?: NonNullable<PrimaryConfig['compositionMode']>): PrimaryConfig;
+/** Copies bindings so retained Scopes never mutate a leased generation's view. */
+export declare function projectPrimaryConfigResources(resources: SnapshotState['resources'], config: PrimaryConfig): Map<PluginId, ReadonlyMap<TokenId, unknown>>;

package/lib/primary-config.js

@@ -1,9 +1,10 @@
 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) {
+export function createPrimaryConfig(document, environment, compositionMode = 'unknown') {
     const safeDocument = freezeConfig(structuredClone(document));
     const expanded = freezeConfig(environment.expandMissingAsEmpty(safeDocument));
     return Object.freeze({
+        compositionMode,
         document: safeDocument,
         expanded,
         get(key) {
@@ -11,6 +12,13 @@ export function createPrimaryConfig(document, environment) {
         },
     });
 }
+/** Copies bindings so retained Scopes never mutate a leased generation's view. */
+export function projectPrimaryConfigResources(resources, config) {
+    return new Map([...resources].map(([owner, bindings]) => [
+        owner,
+        new Map([...bindings, [primaryConfigToken.id, config]]),
+    ]));
+}
 function freezeConfig(value) {
     if (!value || typeof value !== 'object' || Object.isFrozen(value))
         return value;

package/lib/project-graph.d.ts

@@ -1,4 +1,4 @@
-import { type PluginId } from '@zhin.js/plugin-runtime';
+import { type PluginId, type RuntimeConfigDocument } from '@zhin.js/plugin-runtime';
 import type { PackageReference } from './manifest.js';
 import { type PackageResolver, type ResolvedPackage } from './package-resolver.js';
 export interface FeatureRequirementNode {
@@ -28,5 +28,5 @@ export declare class ProjectGraphError extends Error {
 export declare class ProjectGraphService {
     #private;
     constructor(resolver: PackageResolver, engineVersionOrOptions?: string | ProjectGraphServiceOptions);
-    inspect(projectRoot: string): Promise<ProjectGraph>;
+    inspect(projectRoot: string, document?: RuntimeConfigDocument, pluginOrder?: readonly string[]): Promise<ProjectGraph>;
 }

package/lib/project-graph.js

@@ -1,7 +1,8 @@
 import { childPluginId, rootPluginId } from '@zhin.js/plugin-runtime';
+import { PLUGIN_INSTANCE_MIGRATION_GUIDE, readApplicationPluginDeclaration } from './application-plugin-declaration.js';
 import { assertFeatureApi, assertPackageEngine, runtimeEngineVersion, } from './package-contract.js';
 import { PackageResolutionError, } from './package-resolver.js';
-import { PLATFORM_FEATURE_CARRIER, PLATFORM_FEATURE_FACADE, declaredPackageDependency, mergeChildPluginReferences, mergeFeatureReferences, } from './platform-features.js';
+import { PLATFORM_FEATURE_CARRIER, PLATFORM_FEATURE_FACADE, declaredPackageDependency, mergeFeatureReferences, } from './platform-features.js';
 export class ProjectGraphError extends Error {
     constructor(message) {
         super(message);
@@ -21,11 +22,19 @@ export class ProjectGraphService {
             ? []
             : (engineVersionOrOptions.disabledPluginInstanceKeys ?? []));
     }
-    async inspect(projectRoot) {
+    async inspect(projectRoot, document = {}, pluginOrder) {
+        const declaration = readApplicationPluginDeclaration(document, 'Root config', pluginOrder);
+        if (this.#disabledPluginInstanceKeys.size > 0) {
+            throw new ProjectGraphError(`Legacy disabled Plugin state must move to disable_plugins; see ${PLUGIN_INSTANCE_MIGRATION_GUIDE}`);
+        }
         const rootPackage = await this.#resolver.root(projectRoot);
         assertPackageType(rootPackage, 'plugin');
+        if (rootPackage.packageJson.zhin.type === 'plugin'
+            && rootPackage.packageJson.zhin.plugins.length > 0) {
+            throw new ProjectGraphError(`Root package.json#zhin.plugins is no longer supported; see ${PLUGIN_INSTANCE_MIGRATION_GUIDE}`);
+        }
         const packages = new Map();
-        const root = await this.#visitPlugin(rootPackage, rootPluginId(), 'root', undefined, [], packages, true);
+        const root = await this.#visitPlugin(rootPackage, rootPluginId(), 'root', undefined, [], packages, true, declaration);
         for (const pkg of this.#resolver.workspacePackages())
             addPackage(packages, pkg);
         return Object.freeze({
@@ -34,7 +43,7 @@ export class ProjectGraphService {
             buildOrder: topologicalBuildOrder(packages),
         });
     }
-    async #visitPlugin(pkg, id, instanceKey, parent, ancestors, packages, isRoot) {
+    async #visitPlugin(pkg, id, instanceKey, parent, ancestors, packages, isRoot, declaration) {
         if (ancestors.includes(pkg.root)) {
             throw new ProjectGraphError(`Plugin cycle detected: ${[...ancestors, pkg.root].join(' -> ')}`);
         }
@@ -44,7 +53,8 @@ export class ProjectGraphService {
         let featureCarrier;
         let pluginFacade;
         let featureRefs = manifest.features;
-        let pluginRefs = manifest.plugins;
+        const pluginRefs = isRoot
+            ? declaration.instances.filter(item => item.enabled).map(item => ({ package: item.package, instanceKey: item.instanceKey })) : [];
         if (isRoot && manifest.platformFeatures !== false) {
             const platform = await tryResolvePlatform(this.#resolver, pkg);
             featureCarrier = platform.featureCarrier;
@@ -55,15 +65,8 @@ export class ProjectGraphService {
                 const inherited = carrierManifest.type === 'plugin' ? carrierManifest.features : [];
                 featureRefs = mergeFeatureReferences(manifest.features, inherited);
             }
-            if (pluginFacade) {
+            if (pluginFacade)
                 addPackage(packages, pluginFacade);
-                const facadeManifest = pluginFacade.packageJson.zhin;
-                const inheritedPlugins = facadeManifest.type === 'plugin' ? facadeManifest.plugins : [];
-                pluginRefs = mergeChildPluginReferences(manifest.plugins, inheritedPlugins);
-            }
-        }
-        if (isRoot && this.#disabledPluginInstanceKeys.size > 0) {
-            pluginRefs = pluginRefs.filter((reference) => !this.#disabledPluginInstanceKeys.has(reference.instanceKey));
         }
         const featurePackages = new Set();
         const features = await Promise.all(featureRefs.map(async (reference) => {
@@ -80,19 +83,17 @@ export class ProjectGraphService {
             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(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 resolveFrom = ownPluginKeys.has(reference.instanceKey) ? pkg : (pluginFacade ?? pkg);
-            const resolved = await resolveReference(this.#resolver, resolveFrom, reference);
+            const resolved = await resolveReference(this.#resolver, pkg, reference);
             if (!resolved)
                 return undefined;
             assertPackageType(resolved, 'plugin');
-            return this.#visitPlugin(resolved, childPluginId(id, reference.instanceKey), reference.instanceKey, id, [...ancestors, pkg.root], packages, false);
+            return this.#visitPlugin(resolved, childPluginId(id, reference.instanceKey), reference.instanceKey, id, [...ancestors, pkg.root], packages, false, declaration);
         }));
         return Object.freeze({
             id,

package/lib/root-runtime.d.ts

@@ -17,6 +17,8 @@ export interface RootRuntimeOptions {
     readonly environmentVariables?: EnvironmentLayers;
     readonly environmentSource?: EnvironmentLayersPort;
     readonly config?: PluginConfigResolver | RuntimeConfigDocument | ConfigDocumentPort;
+    /** Explicit v2 instance declaration when config is supplied by a custom resolver. */
+    readonly application?: RuntimeConfigDocument;
     readonly installResources?: RootResourceInstaller;
     readonly isolation?: IsolatedPluginRuntimePort;
     readonly onControlError?: ControlErrorHandler;