@zhin.js/runtime 1.1.0 → 1.1.2

package/README.md

@@ -22,6 +22,10 @@ await runtime.start();
 - child/schema 变化替换最浅受影响 subtree。
 - manifest topology transaction 支持 child/Feature 新增、删除和移动。
 - Root/package ABI、lockfile 和未知 importer 变化升级为 process restart。
+- 外部 Root 配置按实际投影分类：子 Plugin 配置只替换对应 subtree，Host 配置请求
+  process restart。
+- `.env` / `.env.<environment>` 由 `EnvironmentLayersPort` 重读；Runtime 重新展开配置引用，
+  Host 投影变化时重启进程，否则提交新的 Plugin generation。
 - 候选校验或 handoff 失败不提交 generation；旧 snapshot 保持可用。
 - 最后一个旧 lease 释放后，旧资源才按 children-first 顺序回收。
 

package/lib/config-composer.d.ts

@@ -1,9 +1,9 @@
+import type { RuntimeConfigDocument } from '@zhin.js/plugin-runtime';
 import type { PluginId } from '@zhin.js/plugin-runtime';
 import type { ProjectGraph } from './project-graph.js';
 /** Host configuration keys consumed by Runtime composition and Host installers. */
 export declare const HOST_CONFIG_KEYS: readonly string[];
 export type JsonSchema = Readonly<Record<string, unknown>>;
-export type RuntimeConfigDocument = Readonly<Record<string, unknown>>;
 export interface ComposedConfig {
     readonly effectiveSchema: JsonSchema;
     readonly document: RuntimeConfigDocument;

package/lib/config-composer.js

@@ -199,12 +199,25 @@ async function readOwnSchema(node) {
             || schema.allOf !== undefined || schema.$ref !== undefined)) {
         throw new TypeError(`${file} root schema must declare properties; composition keywords (anyOf/oneOf/allOf/$ref) are not supported`);
     }
+    const properties = schemaProperties(schema);
+    if (Object.hasOwn(properties, 'commandNamespace')) {
+        throw new ConfigSchemaCollisionError(node.id, 'commandNamespace');
+    }
     return Object.freeze({
         $id: `urn:zhin:plugin-config:${encodeURIComponent(String(node.id))}`,
         type: 'object',
         additionalProperties: false,
         ...schema,
-        properties: schemaProperties(schema),
+        properties: {
+            commandNamespace: {
+                type: 'string',
+                minLength: 1,
+                pattern: '^\\S+(?: \\S+)*$',
+                description: 'Explicit command namespace prepended after the Endpoint commandPrefix.',
+                'x-descriptionZh': '显式指令命名空间；在 Endpoint commandPrefix 之后参与路由。',
+            },
+            ...properties,
+        },
     });
 }
 function schemaProperties(schema) {

package/lib/config-patch-planner.d.ts

@@ -1,22 +1,11 @@
-import { type PluginId } from '@zhin.js/plugin-runtime';
-import { ConfigComposer, type ComposedConfig, type RuntimeConfigDocument } from './config-composer.js';
+import { type ConfigPatch, type PluginId, type RuntimeConfigDocument } from '@zhin.js/plugin-runtime';
+import { ConfigComposer, type ComposedConfig } from './config-composer.js';
 import type { ProjectGraph } from './project-graph.js';
-export type ConfigPatch = {
-    readonly op: 'set';
-    readonly path: readonly string[];
-    readonly value: unknown;
-} | {
-    readonly op: 'remove';
-    readonly path: readonly string[];
-};
 export interface ConfigPatchPlan extends ComposedConfig {
     readonly candidate: RuntimeConfigDocument;
     readonly documentChanged: boolean;
     readonly roots: readonly PluginId[];
 }
-export declare class ConfigPatchPathError extends Error {
-    constructor(message: string);
-}
 /** Validates a candidate document before deriving its minimal replacement forest. */
 export declare class ConfigPatchPlanner {
     private readonly composer;

package/lib/config-patch-planner.js

@@ -1,12 +1,6 @@
 import { isDeepStrictEqual } from 'node:util';
-import { rootPluginId } from '@zhin.js/plugin-runtime';
-import { ConfigComposer, } from './config-composer.js';
-export class ConfigPatchPathError extends Error {
-    constructor(message) {
-        super(message);
-        this.name = 'ConfigPatchPathError';
-    }
-}
+import { applyConfigPatches, rootPluginId, } from '@zhin.js/plugin-runtime';
+import { ConfigComposer } from './config-composer.js';
 /** Validates a candidate document before deriving its minimal replacement forest. */
 export class ConfigPatchPlanner {
     composer;
@@ -15,123 +9,19 @@ export class ConfigPatchPlanner {
     }
     async plan(graph, current, patches) {
         const previous = await this.composer.compose(graph, current);
-        let candidate = structuredClone(current);
-        for (const patch of patches)
-            candidate = applyPatch(candidate, patch);
+        const candidate = applyConfigPatches(current, patches);
         const next = await this.composer.compose(graph, candidate);
         const changed = indexGraph(graph)
             .filter((node) => !isDeepStrictEqual(previous.views.get(node.id), next.views.get(node.id)))
             .map((node) => node.id);
         return Object.freeze({
             ...next,
-            candidate: Object.freeze(candidate),
+            candidate,
             documentChanged: !isDeepStrictEqual(current, candidate),
             roots: Object.freeze(collapseRoots(changed)),
         });
     }
 }
-function applyPatch(document, patch) {
-    assertPath(patch.path);
-    if (patch.path.length === 0) {
-        if (patch.op === 'remove') {
-            throw new ConfigPatchPathError('The config document root cannot be removed');
-        }
-        return cloneDocument(patch.value);
-    }
-    if (patch.op === 'set')
-        setValue(document, patch.path, structuredClone(patch.value));
-    else
-        removeValue(document, patch.path);
-    return document;
-}
-function setValue(document, path, value) {
-    let target = document;
-    for (const [index, segment] of path.slice(0, -1).entries()) {
-        const existing = readChild(target, segment, path.slice(0, index + 1));
-        if (existing === undefined) {
-            // Missing intermediates are always created as records; arrays only ever
-            // come from the existing document (numeric segments index into them).
-            const created = {};
-            target[segment] = created;
-            target = created;
-        }
-        else {
-            target = requireContainer(existing, path.slice(0, index + 1));
-        }
-    }
-    writeChild(target, lastSegment(path), value, path);
-}
-function removeValue(document, path) {
-    let target = document;
-    for (const [index, segment] of path.slice(0, -1).entries()) {
-        const existing = readChild(target, segment, path.slice(0, index + 1));
-        if (existing === undefined)
-            return;
-        target = requireContainer(existing, path.slice(0, index + 1));
-    }
-    const segment = lastSegment(path);
-    if (Array.isArray(target)) {
-        target.splice(arrayIndex(segment, target, path), 1);
-        return;
-    }
-    delete target[segment];
-}
-function cloneDocument(value) {
-    return requireRecord(structuredClone(value), []);
-}
-function readChild(container, segment, path) {
-    if (Array.isArray(container))
-        return container[arrayIndex(segment, container, path)];
-    return container[segment];
-}
-function writeChild(container, segment, value, path) {
-    if (Array.isArray(container)) {
-        container[arrayIndex(segment, container, path)] = value;
-        return;
-    }
-    container[segment] = value;
-}
-/** Resolves a numeric path segment against an array, rejecting non-numeric segments and out-of-bounds indexes. */
-function arrayIndex(segment, container, path) {
-    if (!/^(0|[1-9]\d*)$/.test(segment)) {
-        throw new ConfigPatchPathError(`Config path ${pointer(path)} requires an array index, got "${segment}"`);
-    }
-    const index = Number(segment);
-    if (index >= container.length) {
-        throw new ConfigPatchPathError(`Config path ${pointer(path)} is out of bounds (array length ${container.length})`);
-    }
-    return index;
-}
-function requireContainer(value, path) {
-    if (!value || typeof value !== 'object') {
-        throw new ConfigPatchPathError(`Config path ${pointer(path)} is not an object`);
-    }
-    return value;
-}
-function requireRecord(value, path) {
-    if (!value || typeof value !== 'object' || Array.isArray(value)) {
-        throw new ConfigPatchPathError(`Config path ${pointer(path)} is not an object`);
-    }
-    return value;
-}
-function assertPath(path) {
-    for (const segment of path) {
-        if (!segment || segment === '__proto__' || segment === 'prototype' || segment === 'constructor') {
-            throw new ConfigPatchPathError(`Unsafe config path segment: ${segment || '<empty>'}`);
-        }
-    }
-}
-function lastSegment(path) {
-    const segment = path[path.length - 1];
-    if (!segment)
-        throw new ConfigPatchPathError('Config patch path is empty');
-    return segment;
-}
-function pointer(path) {
-    if (path.length === 0)
-        return '/';
-    return `/${path.map((segment) => segment.replaceAll('~', '~0').replaceAll('/', '~1')).join('/')}`;
-}
 function indexGraph(graph) {
     const result = [];
     const visit = (node) => {

package/lib/convention-capability-delta.js

@@ -28,7 +28,8 @@ export class ConventionCapabilityDeltaResolver {
                     for (const root of roots) {
                         const discovered = await this.#discover(cache, provider, root);
                         for (const candidate of discovered) {
-                            if (candidate.source !== fallback.source)
+                            if (candidate.source !== fallback.source
+                                && !candidate.relatedSources.includes(fallback.source))
                                 continue;
                             const ids = capabilities.get(feature) ?? new Set();
                             ids.add(candidate.id);
@@ -82,6 +83,7 @@ export class ConventionCapabilityDeltaResolver {
             for await (const source of convention.discover(context)) {
                 discovered.push(Object.freeze({
                     source: resolve(source.source),
+                    relatedSources: Object.freeze((source.relatedSources ?? []).map((item) => resolve(item))),
                     id: capabilityId(root.owner, provider.id, source.localName),
                 }));
             }

package/lib/environment-store.d.ts

@@ -6,6 +6,11 @@ export interface EnvironmentLayers {
     readonly environments?: Readonly<Record<string, EnvironmentSource>>;
     readonly plugins?: Readonly<Record<string, EnvironmentSource>>;
 }
+/** Reloadable authority for environment layers and their watched files. */
+export interface EnvironmentLayersPort {
+    readonly sources: readonly string[];
+    read(): Promise<EnvironmentLayers>;
+}
 export interface EnvSchema<T> {
     readonly secretKeys?: readonly string[];
     parse(source: EnvironmentSource): T;

package/lib/hmr-coordinator.d.ts

@@ -3,6 +3,7 @@ import { type GenerationInvalidationPlan, type InvalidationPlan, type ProcessInv
 import type { ModuleRuntime } from './module-runtime.js';
 import type { SourceOwnershipIndex } from './source-ownership.js';
 export interface HmrReloadPort {
+    handlesSource?(source: string): boolean;
     reload(plan: GenerationInvalidationPlan): Promise<ProcessInvalidationPlan | void>;
 }
 export interface HmrCoordinatorOptions {

package/lib/hmr-coordinator.js

@@ -68,7 +68,8 @@ export class HmrCoordinator {
             while (this.#pending.size > 0) {
                 const changed = [...this.#pending];
                 this.#pending.clear();
-                const forcedRestart = changed.filter((source) => this.options.modules.requiresProcessRestart?.(source));
+                const forcedRestart = changed.filter((source) => (!this.options.runtime.handlesSource?.(source)
+                    && this.options.modules.requiresProcessRestart?.(source)));
                 if (forcedRestart.length > 0) {
                     this.#restartRequired = true;
                     this.#pending.clear();

package/lib/host-config-schema.json

@@ -123,10 +123,10 @@
                             "description": "Command allowlist preset used outside full mode.",
                             "x-descriptionZh": "非 full 模式使用的命令白名单预设。"
                         },
-                        "execApprovalMode": { "type": "string", "enum": ["ask", "allow", "deny"], "description": "Approval policy for main Agent commands.", "x-descriptionZh": "主 Agent 命令的审批策略。" },
-                        "subagentExecApprovalMode": { "type": "string", "enum": ["ask", "allow", "deny"], "description": "Approval policy for sub-Agent commands.", "x-descriptionZh": "子 Agent 命令的审批策略。" },
-                        "workerExecApprovalMode": { "type": "string", "enum": ["ask", "allow", "deny"], "description": "Approval policy for worker commands.", "x-descriptionZh": "Worker 命令的审批策略。" },
-                        "taskExecApprovalMode": { "type": "string", "enum": ["ask", "allow", "deny"], "description": "Approval policy for task commands.", "x-descriptionZh": "Task 命令的审批策略。" },
+                        "execApprovalMode": { "type": "string", "enum": ["ask", "bypass", "auto"], "description": "Approval policy for main Agent commands.", "x-descriptionZh": "主 Agent 命令的审批策略。" },
+                        "subagentExecApprovalMode": { "type": "string", "enum": ["ask", "bypass", "auto"], "description": "Approval policy for sub-Agent commands.", "x-descriptionZh": "子 Agent 命令的审批策略。" },
+                        "workerExecApprovalMode": { "type": "string", "enum": ["ask", "bypass", "auto"], "description": "Approval policy for worker commands.", "x-descriptionZh": "Worker 命令的审批策略。" },
+                        "taskExecApprovalMode": { "type": "string", "enum": ["ask", "bypass", "auto"], "description": "Approval policy for task commands.", "x-descriptionZh": "Task 命令的审批策略。" },
                         "toolExecution": {
                             "type": "string",
                             "enum": ["parallel", "sequential", "tiered"],

package/lib/index.d.ts

@@ -1,7 +1,6 @@
 export * from './config-composer.js';
-export * from './config-document.js';
 export * from './config-patch-planner.js';
-export * from './compatibility.js';
+export * from './package-contract.js';
 export * from './environment.js';
 export * from './environment-store.js';
 export * from './hmr-coordinator.js';

package/lib/index.js

@@ -1,7 +1,6 @@
 export * from './config-composer.js';
-export * from './config-document.js';
 export * from './config-patch-planner.js';
-export * from './compatibility.js';
+export * from './package-contract.js';
 export * from './environment.js';
 export * from './environment-store.js';
 export * from './hmr-coordinator.js';

package/lib/native-development-runtime.d.ts

@@ -3,6 +3,12 @@ import type { ModuleRuntime, ModuleWatchRoot } from './module-runtime.js';
 export interface NativeDevelopmentModuleRuntimeOptions {
     readonly projectRoot: string;
     readonly watch?: boolean;
+    /** Optional scoped loader used only when the active Node loader rejects TSX. */
+    readonly tsxLoader?: TsxModuleLoader;
+}
+export interface TsxModuleLoader {
+    load<T = unknown>(source: string, parentURL: string): Promise<T>;
+    close?(): Promise<void>;
 }
 /**
  * Uses Node's native ESM/TypeScript loader and adds only cache busting and watch.

package/lib/native-development-runtime.js

@@ -1,5 +1,5 @@
 import { readdirSync, statSync, watch as watchDirectory, } from 'node:fs';
-import { extname, isAbsolute, relative, resolve, sep } from 'node:path';
+import { basename, extname, isAbsolute, relative, resolve, sep } from 'node:path';
 import { pathToFileURL } from 'node:url';
 const ignoredDirectories = new Set([
     '.git', '.zhin', 'coverage', 'data', 'dist', 'lib', 'node_modules',
@@ -8,7 +8,7 @@ const watchedExtensions = new Set([
     '.cjs', '.js', '.json', '.md', '.mjs', '.ts', '.tsx', '.yaml', '.yml',
 ]);
 const capabilityRoots = new Set([
-    'adapters', 'agents', 'commands', 'components', 'handlers', 'mcp', 'middlewares', 'pages', 'skills', 'tools',
+    'adapters', 'agents', 'commands', 'components', 'handlers', 'hooks', 'mcps', 'middlewares', 'pages', 'prompt-sections', 'schedules', 'skills', 'tools',
 ]);
 /**
  * Uses Node's native ESM/TypeScript loader and adds only cache busting and watch.
@@ -18,6 +18,7 @@ const capabilityRoots = new Set([
 export class NativeDevelopmentModuleRuntime {
     #projectRoot;
     #watchEnabled;
+    #tsxLoader;
     #revisions = new Map();
     #watchers = new Set();
     #watchRoots;
@@ -25,19 +26,25 @@ export class NativeDevelopmentModuleRuntime {
     constructor(options) {
         this.#projectRoot = resolve(options.projectRoot);
         this.#watchEnabled = options.watch ?? true;
+        this.#tsxLoader = options.tsxLoader;
         this.#watchRoots = normalizeWatchRoots([this.#projectRoot]);
     }
     async load(source) {
         this.#assertOpen();
         const normalized = resolve(source);
-        if (normalized.endsWith('.tsx')) {
-            throw new Error(`Node native TypeScript does not support TSX: ${normalized}`);
-        }
         if (normalized.endsWith('.ts'))
             assertNativeTypeScriptSupport();
         const url = pathToFileURL(normalized);
         url.searchParams.set('zhin-generation', String(this.#revisions.get(normalized) ?? 0));
-        return import(url.href);
+        try {
+            return await import(url.href);
+        }
+        catch (error) {
+            if (!normalized.endsWith('.tsx') || !isUnsupportedTsxError(error) || !this.#tsxLoader) {
+                throw error;
+            }
+            return this.#tsxLoader.load(url.href, pathToFileURL(`${this.#projectRoot}${sep}`).href);
+        }
     }
     invalidate(source) {
         const normalized = resolve(source);
@@ -50,23 +57,40 @@ export class NativeDevelopmentModuleRuntime {
         // The HMR coordinator turns this into a visible process restart reason.
         if (!packageRoot || isNodeModulesSource(packageRoot, normalized))
             return true;
+        if (packageRoot === this.#projectRoot && basename(normalized).startsWith('.env'))
+            return true;
         const parts = relative(packageRoot, normalized).split(sep);
         const capability = parts.findIndex((part) => capabilityRoots.has(part));
         if (capability < 0)
             return isExecutableSource(normalized);
         const root = parts[capability];
-        if (root === 'pages')
-            return false;
-        if (root === 'skills' || root === 'agents')
+        if (root === 'agents' || root === 'skills') {
+            const local = parts.slice(capability + 1);
+            if (isNestedDirectoryEntry(local))
+                return false;
             return extname(normalized) !== '.md';
-        if (root === 'tools' || root === 'mcp')
-            return parts.length !== capability + 2;
-        if (isCapabilityEntry(parts.slice(capability + 1)))
-            return false;
+        }
+        if (root === 'commands') {
+            const local = parts.slice(capability + 1);
+            if (!isExecutableSource(normalized))
+                return extname(normalized) === '.json';
+            return local.length < 2
+                || !local.slice(0, -1).every(isCommandDirectorySegment);
+        }
+        if (root === 'adapters' || root === 'components' || root === 'handlers'
+            || root === 'hooks' || root === 'mcps' || root === 'middlewares'
+            || root === 'pages' || root === 'prompt-sections' || root === 'schedules'
+            || root === 'tools') {
+            const local = parts.slice(capability + 1);
+            if (!isExecutableSource(normalized))
+                return extname(normalized) === '.json';
+            return local.length < 2
+                || !isNamedCapabilityDirectory(local[0] ?? '', root === 'tools');
+        }
         // Support files inside capability directories (e.g. commands/_utils.ts)
         // are not discovery entries: reloading the entry URL only bumps that
         // entry's zhin-generation, so the importer closure keeps the old code.
-        return ['.js', '.json', '.ts'].includes(extname(normalized));
+        return ['.js', '.json', '.ts', '.tsx'].includes(extname(normalized));
     }
     updateWatchRoots(roots) {
         this.#assertOpen();
@@ -98,12 +122,34 @@ export class NativeDevelopmentModuleRuntime {
         for (const watcher of this.#watchers)
             watcher.close();
         this.#watchers.clear();
+        await this.#tsxLoader?.close?.();
     }
     #assertOpen() {
         if (this.#closed)
             throw new Error('NativeDevelopmentModuleRuntime is closed');
     }
 }
+function isCommandDirectorySegment(value) {
+    return /^[a-z0-9][a-z0-9-]*$/u.test(value)
+        || (!/[A-Z]/u.test(value) && /[^\x00-\x7F]/u.test(value) && !/[\s/\\]/u.test(value))
+        || /^\[(?:\[)?(?:\.\.\.)?[a-zA-Z][a-zA-Z0-9]*\](?:\])?$/u.test(value);
+}
+function isNamedCapabilityDirectory(value, allowSnake) {
+    return allowSnake
+        ? /^[a-z0-9][a-z0-9_-]*$/u.test(value)
+        : /^[a-z0-9][a-z0-9-]*$/u.test(value);
+}
+function isDirectoryCapabilityEntry(parts) {
+    return parts.length === 2
+        && parts[1] === `index${extname(parts[1] ?? '')}`
+        && ['.cjs', '.js', '.mjs', '.ts', '.tsx'].includes(extname(parts[1] ?? ''));
+}
+function isNestedDirectoryEntry(parts) {
+    const index = parts.indexOf('tools');
+    const hookIndex = parts.indexOf('hooks');
+    const capability = index >= 0 ? index : hookIndex;
+    return capability >= 1 && isDirectoryCapabilityEntry(parts.slice(capability + 1));
+}
 export function supportsNativeTypeScript(version = process.versions.node, execArguments = process.execArgv, nodeOptions = process.env.NODE_OPTIONS ?? '') {
     if (execArguments.includes('--experimental-strip-types')
         || /(?:^|\s)--experimental-strip-types(?:\s|$)/u.test(nodeOptions))
@@ -119,6 +165,11 @@ export function assertNativeTypeScriptSupport() {
         'Use Node >=22.18.0 or start Node with --experimental-strip-types.',
     ].join(' '));
 }
+function isUnsupportedTsxError(error) {
+    return error instanceof Error
+        && 'code' in error
+        && error.code === 'ERR_UNKNOWN_FILE_EXTENSION';
+}
 class PortableSourceWatcher {
     listener;
     #watchers = new Set();
@@ -238,21 +289,6 @@ function isWatchedSource(source) {
 function isIgnoredSource(root, source) {
     return relative(root, source).split(sep).some((segment) => ignoredDirectories.has(segment));
 }
-/**
- * Discovery entries follow the typeScriptModules convention
- * (feature-kit typescript-convention.ts): lowercase segment directories and
- * lowercase .ts/.tsx module names only.
- */
-function isCapabilityEntry(segments) {
-    const file = segments[segments.length - 1] ?? '';
-    return segments.slice(0, -1).every(isCapabilitySegment) && isCapabilityModule(file);
-}
-function isCapabilitySegment(value) {
-    return /^[a-z0-9][a-z0-9-]*$/u.test(value);
-}
-function isCapabilityModule(value) {
-    return /^[a-z0-9][a-z0-9-]*\.tsx?$/u.test(value);
-}
 function isExecutableSource(source) {
     return ['.cjs', '.js', '.mjs', '.ts', '.tsx'].includes(extname(source));
 }

package/lib/{compatibility.d.ts → package-contract.d.ts}

@@ -1,7 +1,7 @@
 import type { PackageReference } from './manifest.js';
 import type { ResolvedPackage } from './package-resolver.js';
 export declare const runtimeEngineVersion = "1.0.0";
-export declare class PackageCompatibilityError extends Error {
+export declare class PackageContractError extends Error {
     readonly packageName: string;
     readonly contract: 'engine' | 'feature-api';
     constructor(packageName: string, contract: 'engine' | 'feature-api', message: string);

package/lib/{compatibility.js → package-contract.js}

@@ -2,14 +2,14 @@ import { createRequire } from 'node:module';
 const require = createRequire(import.meta.url);
 const semver = require('semver');
 export const runtimeEngineVersion = '1.0.0';
-export class PackageCompatibilityError extends Error {
+export class PackageContractError extends Error {
     packageName;
     contract;
     constructor(packageName, contract, message) {
-        super(`Incompatible ${contract} for ${packageName}: ${message}`);
+        super(`Invalid ${contract} contract for ${packageName}: ${message}`);
         this.packageName = packageName;
         this.contract = contract;
-        this.name = 'PackageCompatibilityError';
+        this.name = 'PackageContractError';
     }
 }
 export function assertPackageEngine(pkg, engineVersion = runtimeEngineVersion) {
@@ -18,7 +18,7 @@ export function assertPackageEngine(pkg, engineVersion = runtimeEngineVersion) {
         return;
     assertRange(pkg.name, 'engine', range);
     if (!semver.satisfies(engineVersion, range, { includePrerelease: true })) {
-        throw new PackageCompatibilityError(pkg.name, 'engine', `requires ${range}, Runtime provides ${engineVersion}`);
+        throw new PackageContractError(pkg.name, 'engine', `requires ${range}, Runtime provides ${engineVersion}`);
     }
 }
 export function assertFeatureApi(owner, reference, feature) {
@@ -26,20 +26,20 @@ export function assertFeatureApi(owner, reference, feature) {
         ? feature.packageJson.zhin.featureApi
         : undefined;
     if (actual && !semver.valid(actual)) {
-        throw new PackageCompatibilityError(feature.name, 'feature-api', `declares invalid featureApi version ${actual}`);
+        throw new PackageContractError(feature.name, 'feature-api', `declares invalid featureApi version ${actual}`);
     }
     if (!reference.api)
         return;
     assertRange(owner.name, 'feature-api', reference.api);
     if (!actual) {
-        throw new PackageCompatibilityError(feature.name, 'feature-api', `must declare a valid featureApi version for ${owner.name}'s ${reference.api} requirement`);
+        throw new PackageContractError(feature.name, 'feature-api', `must declare a valid featureApi version for ${owner.name}'s ${reference.api} requirement`);
     }
     if (!semver.satisfies(actual, reference.api, { includePrerelease: true })) {
-        throw new PackageCompatibilityError(feature.name, 'feature-api', `${owner.name} requires ${reference.api}, provider declares ${actual}`);
+        throw new PackageContractError(feature.name, 'feature-api', `${owner.name} requires ${reference.api}, provider declares ${actual}`);
     }
 }
 function assertRange(packageName, contract, range) {
     if (!semver.validRange(range)) {
-        throw new PackageCompatibilityError(packageName, contract, `invalid semver range ${range}`);
+        throw new PackageContractError(packageName, contract, `invalid semver range ${range}`);
     }
 }

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

@@ -5,7 +5,7 @@ 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 './config-composer.js';
+import type { RuntimeConfigDocument } from '@zhin.js/plugin-runtime';
 export type PluginConfigResolver = (node: PluginGraphNode) => unknown;
 export interface RootResourceContext {
     /** Exact shadow generation being assembled; never inferred from a latest snapshot. */
@@ -53,10 +53,6 @@ export declare class PluginScopeAssembler {
     createdScopeDisposers(): readonly (readonly [PluginId, Dispose])[];
     generationHandoff(): GenerationHandoff | undefined;
     setupCapabilities(): readonly Readonly<SetupCapabilityRegistration>[];
-    /**
-     * Root resources are process-owned. A Plugin Scope receives only a facade
-     * that translates logical table/job names to its owner namespace. The root
-     * owner deliberately keeps bare names for backward-compatible projects.
-     */
+    /** Root resources are process-owned; every Plugin Scope receives an owner-bound facade. */
     private installOwnerScopedHosts;
 }

package/lib/plugin-scope-assembler.js

@@ -1,5 +1,5 @@
 import { resolve } from 'node:path';
-import { GenerationHandoffStack, Scope, capabilityId, createGenerationAdmissionGate, createToken, createPluginDatabaseHost, createPluginScheduleHost, databaseHostToken, databaseRootHostToken, featureId, rootPluginId, scheduleHostToken, scheduleRootHostToken, unwrapPluginDatabaseHost, unwrapPluginScheduleHost, } from '@zhin.js/plugin-runtime';
+import { GenerationHandoffStack, Scope, capabilityId, createGenerationAdmissionGate, createToken, PluginDatabaseHost, PluginScheduleHost, databaseHostToken, databaseRootHostToken, 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';
@@ -212,27 +212,19 @@ export class PluginScopeAssembler {
     setupCapabilities() {
         return Object.freeze([...this.#setupCapabilities.values()]);
     }
-    /**
-     * Root resources are process-owned. A Plugin Scope receives only a facade
-     * that translates logical table/job names to its owner namespace. The root
-     * owner deliberately keeps bare names for backward-compatible projects.
-     */
+    /** Root resources are process-owned; every Plugin Scope receives an owner-bound facade. */
     installOwnerScopedHosts(scope, owner) {
         const database = scope.has(databaseRootHostToken)
             ? scope.use(databaseRootHostToken)
-            : scope.has(databaseHostToken)
-                ? unwrapPluginDatabaseHost(scope.use(databaseHostToken))
-                : undefined;
+            : undefined;
         if (database) {
-            scope.provide(databaseHostToken, createPluginDatabaseHost(owner, database));
+            scope.provide(databaseHostToken, new PluginDatabaseHost(owner, database));
         }
         const schedule = scope.has(scheduleRootHostToken)
             ? scope.use(scheduleRootHostToken)
-            : scope.has(scheduleHostToken)
-                ? unwrapPluginScheduleHost(scope.use(scheduleHostToken))
-                : undefined;
+            : undefined;
         if (schedule) {
-            scope.provide(scheduleHostToken, createPluginScheduleHost(owner, schedule));
+            scope.provide(scheduleHostToken, new PluginScheduleHost(owner, schedule));
         }
     }
 }

package/lib/primary-config.d.ts

@@ -1,5 +1,5 @@
 import type { EnvStore } from './environment-store.js';
-import type { RuntimeConfigDocument } from './config-composer.js';
+import type { RuntimeConfigDocument } from '@zhin.js/plugin-runtime';
 /**
  * Generation-owned, validated Root configuration.
  *

package/lib/project-graph.js

@@ -1,5 +1,5 @@
 import { childPluginId, rootPluginId } from '@zhin.js/plugin-runtime';
-import { assertFeatureApi, assertPackageEngine, runtimeEngineVersion, } from './compatibility.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';
 export class ProjectGraphError extends Error {

package/lib/root-runtime.d.ts

@@ -1,9 +1,6 @@
-import { type ControlErrorHandler, type GenerationCommitListener, type PluginId, type RuntimeSnapshot, type SnapshotReader } from '@zhin.js/plugin-runtime';
-import { type RuntimeConfigDocument } from './config-composer.js';
-import { type ConfigDocumentPort } from './config-document.js';
-import { type ConfigPatch } from './config-patch-planner.js';
+import { type ControlErrorHandler, type ConfigDocumentPort, type ConfigPatch, type GenerationCommitListener, type PluginId, type RuntimeConfigDocument, type RuntimeSnapshot, type SnapshotReader } from '@zhin.js/plugin-runtime';
 import { type RuntimeEnvironment } from './environment.js';
-import { type EnvironmentLayers } from './environment-store.js';
+import { type EnvironmentLayers, type EnvironmentLayersPort } from './environment-store.js';
 import type { IsolatedPluginRuntimePort } from './isolation.js';
 import type { ModuleRuntime } from './module-runtime.js';
 import { type PluginConfigResolver, type RootResourceInstaller } from './plugin-scope-assembler.js';
@@ -17,6 +14,7 @@ export interface RootRuntimeOptions {
     readonly modules: ModuleRuntime;
     readonly environment: RuntimeEnvironment;
     readonly environmentVariables?: EnvironmentLayers;
+    readonly environmentSource?: EnvironmentLayersPort;
     readonly config?: PluginConfigResolver | RuntimeConfigDocument | ConfigDocumentPort;
     readonly installResources?: RootResourceInstaller;
     readonly isolation?: IsolatedPluginRuntimePort;

package/lib/root-runtime.js

@@ -1,10 +1,9 @@
 import { resolve } from 'node:path';
 import { isDeepStrictEqual } from 'node:util';
-import { DisposeStack, GenerationHandoffStack, RootController, createSnapshotView, rootPluginId, } from '@zhin.js/plugin-runtime';
+import { DisposeStack, GenerationHandoffStack, RootController, ConfigDocumentDivergenceError, createSnapshotView, rootPluginId, } from '@zhin.js/plugin-runtime';
 import { FeatureCatalog, FeatureDiscovery, } from '@zhin.js/feature-kit';
 import { ConfigComposer } from './config-composer.js';
-import { ConfigDocumentDivergenceError, } from './config-document.js';
-import { ConfigPatchPlanner, } from './config-patch-planner.js';
+import { ConfigPatchPlanner } from './config-patch-planner.js';
 import { defineRuntimeEnvironment } from './environment.js';
 import { createEnvStore, defineEnvironmentLayers, } from './environment-store.js';
 import { FeatureProjector, composeGenerationHandoffs, } from './feature-projector.js';
@@ -23,11 +22,14 @@ import { addCapabilitySlot, featureSetupAliases, mergeSetupCapabilities, } from
 import { SubtreeGenerationPreparer, SubtreeTopologyChangedError, } from './subtree-generation-preparer.js';
 import { TopologyGenerationPreparer } from './topology-generation-preparer.js';
 import { RestartBoundaryPlanner } from './restart-boundary.js';
+import { RuntimeInputPlanner } from './runtime-input-planner.js';
 export class RootRuntime {
     #projectRoot;
     #modules;
     #environment;
     #environmentLayers;
+    #environmentSource;
+    #runtimeInputSources;
     #configResolver;
     #configPort;
     #configSnapshot;
@@ -43,12 +45,17 @@ export class RootRuntime {
         this.#modules = options.modules;
         this.#environment = defineRuntimeEnvironment(options.environment);
         this.#environmentLayers = defineEnvironmentLayers(options.environmentVariables);
+        this.#environmentSource = options.environmentSource;
         if (typeof options.config === 'function')
             this.#configResolver = options.config;
         else if (isConfigDocumentPort(options.config))
             this.#configPort = options.config;
         else
             this.#configDocument = structuredClone(options.config ?? {});
+        this.#runtimeInputSources = new Set([
+            ...(this.#configPort?.sources ?? []),
+            ...(this.#environmentSource?.sources ?? []),
+        ].map((source) => resolve(source)));
         this.#installResources = options.installResources;
         this.#isolation = options.isolation;
         this.#disabledPluginInstanceKeys = Object.freeze([...(options.disabledPluginInstanceKeys ?? [])]);
@@ -67,6 +74,9 @@ export class RootRuntime {
         return this.#controller.committed.state.ownership;
     }
     async start() {
+        if (this.#environmentSource) {
+            this.#environmentLayers = defineEnvironmentLayers(await this.#environmentSource.read());
+        }
         if (this.#configPort) {
             const snapshot = await this.#configPort.read();
             this.#configSnapshot = snapshot;
@@ -95,6 +105,7 @@ export class RootRuntime {
             modules: this.#modules,
             ownership: () => this.sourceOwnership,
             runtime: {
+                handlesSource: (source) => this.#runtimeInputSources.has(resolve(source)),
                 reload: async (plan) => {
                     const result = await this.#reloadPlan(plan);
                     return isProcessPlan(result) ? result : undefined;
@@ -120,40 +131,115 @@ export class RootRuntime {
         return result;
     }
     async #reloadPlan(plan) {
+        const inputs = await this.#planRuntimeInputs(plan.changed);
+        if (inputs && 'kind' in inputs)
+            return inputs;
+        const previousInputs = inputs ? this.#runtimeInputState() : undefined;
+        const effectiveInputPlan = inputs
+            ? Object.freeze({
+                ...plan,
+                subtrees: collapseInvalidationSubtrees([...plan.subtrees, ...inputs.roots]),
+                fallbacks: Object.freeze(plan.fallbacks.filter((fallback) => !inputs.inputSources.has(resolve(fallback.source)))),
+            })
+            : plan;
         let restart;
-        const snapshot = await this.#controller.reload(plan.subtrees[0] ?? plan.slots[0] ?? rootPluginId(), async (current, signal) => {
+        const snapshot = await this.#controller.reload(effectiveInputPlan.subtrees[0] ?? effectiveInputPlan.slots[0] ?? rootPluginId(), async (current, signal) => {
             let prepared;
-            const resolved = await this.#resolveCapabilityDelta(current, plan);
+            const resolved = await this.#resolveCapabilityDelta(current, effectiveInputPlan);
             const effective = resolved.plan;
+            if (inputs
+                && effective.manifestSources.length === 0
+                && effective.subtrees.length === 0
+                && effective.slots.length === 0
+                && resolved.capabilities.size === 0)
+                return undefined;
             if (this.#model && effective.manifestSources.length > 0) {
-                const inspected = await this.#inspectProject();
+                const inspected = await this.#inspectProject(inputs?.document, inputs?.environmentLayers);
                 restart = new RestartBoundaryPlanner().plan(this.#model.graph, inspected.graph, effective.changed);
                 if (restart)
                     return undefined;
                 prepared = effective.subtrees.includes(rootPluginId())
                     ? await this.#prepareInspected(current, inspected, signal)
-                    : await new TopologyGenerationPreparer(this.#modules, this.#model, inspected.graph, inspected.configResolver, inspected.primaryConfigDocument, this.#environment, this.#installResources, this.#environmentLayers, this.#isolation).prepare(current, signal, { ...effective, capabilities: resolved.capabilities });
+                    : await new TopologyGenerationPreparer(this.#modules, this.#model, inspected.graph, inspected.configResolver, inspected.primaryConfigDocument, this.#environment, this.#installResources, inspected.environmentLayers, this.#isolation).prepare(current, signal, { ...effective, capabilities: resolved.capabilities });
             }
             else if (effective.subtrees.length === 0 && resolved.capabilities.size > 0 && this.#model) {
                 prepared = await new SlotGenerationPreparer(this.#modules, this.#model)
                     .prepare(current, resolved.capabilities, signal);
             }
             else if (this.#model && this.#canPrepareSubtrees(effective)) {
-                const inspected = await this.#inspectProject();
+                const inspected = await this.#inspectProject(inputs?.document, inputs?.environmentLayers);
                 prepared = await this.#prepareSubtrees(current, inspected, effective.subtrees, signal);
             }
             else {
-                prepared = await this.#prepare(current, signal);
+                prepared = await this.#prepare(current, signal, inputs?.document, inputs?.environmentLayers);
             }
-            return prepared?.generation;
+            if (!prepared)
+                return undefined;
+            return inputs && previousInputs
+                ? withRuntimeInputHandoff(prepared.generation, () => this.#adoptRuntimeInputs(inputs), () => this.#restoreRuntimeInputs(previousInputs))
+                : prepared.generation;
         });
         if (restart)
             return restart;
+        if (inputs)
+            this.#adoptRuntimeInputs(inputs);
         return snapshot;
     }
     get #model() {
         return this.#controller.committed.state.model;
     }
+    async #planRuntimeInputs(changed) {
+        const inputSources = new Set(changed.map((source) => resolve(source)).filter((source) => this.#runtimeInputSources.has(source)));
+        if (inputSources.size === 0 || !this.#model)
+            return undefined;
+        const configChanged = this.#configPort?.sources?.some((source) => inputSources.has(resolve(source))) ?? false;
+        const environmentChanged = this.#environmentSource?.sources.some((source) => inputSources.has(resolve(source))) ?? false;
+        const configSnapshot = configChanged ? await this.#configPort?.read() : undefined;
+        const document = configSnapshot?.document ?? requireConfigDocument(this.#configDocument);
+        const environmentLayers = environmentChanged && this.#environmentSource
+            ? defineEnvironmentLayers(await this.#environmentSource.read())
+            : this.#environmentLayers;
+        const inputPlan = await new RuntimeInputPlanner(new ConfigComposer(this.#disabledPluginInstanceKeys)).plan({
+            graph: this.#model.graph,
+            environment: this.#environment,
+            previousDocument: requireConfigDocument(this.#configDocument),
+            nextDocument: document,
+            previousEnvironment: this.#environmentLayers,
+            nextEnvironment: environmentLayers,
+        });
+        if (inputPlan.hostKeys.length > 0) {
+            return Object.freeze({
+                kind: 'process',
+                changed: Object.freeze([...changed].map((source) => resolve(source))),
+                reasons: Object.freeze(inputPlan.hostKeys.map((key) => `Host configuration changed: ${key}`)),
+            });
+        }
+        return Object.freeze({
+            document,
+            configSnapshot,
+            environmentLayers,
+            inputSources,
+            roots: inputPlan.roots,
+        });
+    }
+    #adoptRuntimeInputs(candidate) {
+        this.#configDocument = structuredClone(candidate.document);
+        if (candidate.configSnapshot)
+            this.#configSnapshot = candidate.configSnapshot;
+        this.#environmentLayers = candidate.environmentLayers;
+    }
+    #runtimeInputState() {
+        return Object.freeze({
+            document: this.#configDocument,
+            configSnapshot: this.#configSnapshot,
+            environmentLayers: this.#environmentLayers,
+        });
+    }
+    #restoreRuntimeInputs(state) {
+        this.#configDocument = state.document;
+        this.#configSnapshot = state.configSnapshot;
+        this.#environmentLayers = state.environmentLayers;
+    }
     async #resolveCapabilityDelta(current, plan) {
         const known = capabilityDeltaFromSlots(current, plan.slots);
         if (!this.#model || (plan.fallbacks.length === 0 && plan.slots.length === 0)) {
@@ -177,35 +263,41 @@ export class RootRuntime {
         if (plan.subtrees.length === 0 || plan.subtrees.includes(rootPluginId()))
             return false;
         return plan.changed.every((source) => {
+            if (this.#runtimeInputSources.has(resolve(source)))
+                return true;
             const records = this.sourceOwnership.recordsFor(source);
             return records.length > 0 && records.every((record) => record.role === 'plugin' || record.role === 'schema');
         });
     }
-    async #prepare(current, signal) {
+    async #prepare(current, signal, document, environmentLayers) {
         signal.throwIfAborted();
-        const inspected = await this.#inspectProject();
+        const inspected = await this.#inspectProject(document, environmentLayers);
         signal.throwIfAborted();
         return this.#prepareInspected(current, inspected, signal);
     }
-    async #inspectProject() {
+    async #inspectProject(document, environmentLayers = this.#environmentLayers) {
         const resolver = await NodePackageResolver.create(this.#projectRoot);
         const graph = await new ProjectGraphService(resolver, {
             disabledPluginInstanceKeys: this.#disabledPluginInstanceKeys,
         }).inspect(this.#projectRoot);
-        await this.#refreshConfigDocument();
+        if (document === undefined)
+            await this.#refreshConfigDocument();
+        const activeDocument = document ?? this.#configDocument;
         if (this.#configResolver) {
             return {
                 graph,
                 configResolver: this.#configResolver,
                 primaryConfigDocument: Object.freeze({}),
+                environmentLayers,
             };
         }
         const composed = await new ConfigComposer(this.#disabledPluginInstanceKeys)
-            .compose(graph, this.#configDocument);
+            .compose(graph, activeDocument);
         return {
             graph,
-            configResolver: this.#configViewResolver(composed.views),
+            configResolver: this.#configViewResolver(composed.views, environmentLayers),
             primaryConfigDocument: composed.document,
+            environmentLayers,
         };
     }
     /**
@@ -224,13 +316,13 @@ export class RootRuntime {
         this.#configSnapshot = snapshot;
         this.#configDocument = structuredClone(snapshot.document);
     }
-    #configViewResolver(views) {
-        const env = createEnvStore(rootPluginId(), this.#environment, this.#environmentLayers);
+    #configViewResolver(views, environmentLayers = this.#environmentLayers) {
         return (node) => {
             const view = views.get(node.id);
             if (view === undefined)
                 return undefined;
-            return env.expandMissingAsEmpty(view);
+            return createEnvStore(node.id, this.#environment, environmentLayers)
+                .expandMissingAsEmpty(view);
         };
     }
     async #applyConfigPatches(patches) {
@@ -278,11 +370,12 @@ export class RootRuntime {
                     graph,
                     configResolver: this.#configViewResolver(planned.views),
                     primaryConfigDocument: planned.document,
+                    environmentLayers: this.#environmentLayers,
                 };
                 // Root resources may consume any Primary Config section. Reinstall them
                 // when present so a committed patch cannot leave Host services on the
                 // previous generation's document.
-                if (!this.#installResources && this.#model && !planned.roots.includes(rootPluginId())) {
+                if (this.#model && !planned.roots.includes(rootPluginId()) && planned.roots.length > 0) {
                     prepared = await this.#prepareSubtrees(current, inspected, planned.roots, signal);
                 }
                 else {
@@ -308,14 +401,14 @@ export class RootRuntime {
         return snapshot;
     }
     #prepareInspected(current, inspected, signal) {
-        const assembler = new GenerationAssembler(inspected.graph, this.#modules, inspected.configResolver, inspected.primaryConfigDocument, 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, inspected.environmentLayers, this.#isolation);
         return assembler.prepare(signal);
     }
     async #prepareSubtrees(current, inspected, roots, signal) {
         if (!this.#model)
             return this.#prepareInspected(current, inspected, signal);
         try {
-            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, signal);
+            return await new SubtreeGenerationPreparer(this.#modules, this.#model, inspected.graph, inspected.configResolver, inspected.primaryConfigDocument, this.#environment, this.#installResources, inspected.environmentLayers, this.#isolation).prepare(current, roots, signal);
         }
         catch (error) {
             if (!(error instanceof SubtreeTopologyChangedError))
@@ -347,6 +440,13 @@ function withConfigDocumentHandoff(generation, document, committed) {
     });
     return { ...generation, handoff: handoffs.seal() };
 }
+function withRuntimeInputHandoff(generation, activate, deactivate) {
+    const handoffs = new GenerationHandoffStack();
+    if (generation.handoff)
+        handoffs.add(generation.handoff);
+    handoffs.add({ activateNext: activate, deactivateNext: deactivate });
+    return { ...generation, handoff: handoffs.seal() };
+}
 function isConfigDocumentPort(value) {
     if (!value || typeof value !== 'object')
         return false;

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

@@ -0,0 +1,24 @@
+import { type PluginId, type RuntimeConfigDocument } from '@zhin.js/plugin-runtime';
+import { ConfigComposer, type ComposedConfig } from './config-composer.js';
+import { type EnvironmentLayers } from './environment-store.js';
+import type { RuntimeEnvironment } from './environment.js';
+import type { ProjectGraph } from './project-graph.js';
+export interface RuntimeInputPlan {
+    readonly composed: ComposedConfig;
+    readonly roots: readonly PluginId[];
+    readonly hostKeys: readonly string[];
+    readonly environmentChanged: boolean;
+}
+/** Classifies config/environment changes by their actual expanded runtime projection. */
+export declare class RuntimeInputPlanner {
+    private readonly composer;
+    constructor(composer?: ConfigComposer);
+    plan(options: {
+        readonly graph: ProjectGraph;
+        readonly environment: RuntimeEnvironment;
+        readonly previousDocument: RuntimeConfigDocument;
+        readonly nextDocument: RuntimeConfigDocument;
+        readonly previousEnvironment: EnvironmentLayers;
+        readonly nextEnvironment: EnvironmentLayers;
+    }): Promise<RuntimeInputPlan>;
+}

package/lib/runtime-input-planner.js

@@ -0,0 +1,65 @@
+import { isDeepStrictEqual } from 'node:util';
+import { rootPluginId, } from '@zhin.js/plugin-runtime';
+import { ConfigComposer, HOST_CONFIG_KEYS } from './config-composer.js';
+import { createEnvStore, } from './environment-store.js';
+/** Classifies config/environment changes by their actual expanded runtime projection. */
+export class RuntimeInputPlanner {
+    composer;
+    constructor(composer = new ConfigComposer()) {
+        this.composer = composer;
+    }
+    async plan(options) {
+        const previous = await this.composer.compose(options.graph, options.previousDocument);
+        const next = await this.composer.compose(options.graph, options.nextDocument);
+        const environmentChanged = !isDeepStrictEqual(options.previousEnvironment, options.nextEnvironment);
+        const hostKeys = HOST_CONFIG_KEYS.filter((key) => !isDeepStrictEqual(expandHostValue(previous.document[key], options.environment, options.previousEnvironment), expandHostValue(next.document[key], options.environment, options.nextEnvironment)));
+        const changed = indexGraph(options.graph)
+            .filter((node) => !isDeepStrictEqual(expandPluginView(node.id, previous.views.get(node.id), options.environment, options.previousEnvironment), expandPluginView(node.id, next.views.get(node.id), options.environment, options.nextEnvironment)))
+            .map((node) => node.id);
+        // EnvStore is itself a public Plugin resource. A changed global layer can
+        // affect direct env.get()/parse() consumers even when no ${VAR} occurs in
+        // config, so conservatively rebuild the Root generation when no narrower
+        // config-derived owner proves the impact.
+        const roots = environmentChanged ? [rootPluginId()] : collapseRoots(changed);
+        return Object.freeze({
+            composed: next,
+            roots: Object.freeze(roots),
+            hostKeys: Object.freeze(hostKeys),
+            environmentChanged,
+        });
+    }
+}
+function expandHostValue(value, environment, layers) {
+    return createEnvStore(rootPluginId(), environment, layers).expandMissingAsEmpty(value);
+}
+function expandPluginView(owner, value, environment, layers) {
+    return createEnvStore(owner, environment, layers).expandMissingAsEmpty(value);
+}
+function indexGraph(graph) {
+    const result = [];
+    const visit = (node) => {
+        result.push(node);
+        for (const child of node.children)
+            visit(child);
+    };
+    visit(graph.root);
+    return result;
+}
+function collapseRoots(plugins) {
+    if (plugins.includes(rootPluginId()))
+        return [rootPluginId()];
+    const selected = new Set(plugins);
+    return plugins.filter((plugin) => {
+        let parent = parentPlugin(plugin);
+        while (parent) {
+            if (selected.has(parent))
+                return false;
+            parent = parentPlugin(parent);
+        }
+        return true;
+    });
+}
+function parentPlugin(plugin) {
+    const separator = plugin.lastIndexOf('/');
+    return separator < 0 ? undefined : plugin.slice(0, separator);
+}

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

@@ -1,7 +1,7 @@
 import { type PluginId, type RuntimeSnapshot } from '@zhin.js/plugin-runtime';
 import type { RuntimeEnvironment } from './environment.js';
 import type { EnvironmentLayers } from './environment-store.js';
-import type { RuntimeConfigDocument } from './config-composer.js';
+import type { RuntimeConfigDocument } from '@zhin.js/plugin-runtime';
 import type { IsolatedPluginRuntimePort } from './isolation.js';
 import type { ModuleRuntime } from './module-runtime.js';
 import { type PluginConfigResolver, type RootResourceInstaller } from './plugin-scope-assembler.js';

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

@@ -1,7 +1,7 @@
 import { type CapabilityId, type PluginId, type RuntimeSnapshot } from '@zhin.js/plugin-runtime';
 import type { RuntimeEnvironment } from './environment.js';
 import type { EnvironmentLayers } from './environment-store.js';
-import type { RuntimeConfigDocument } from './config-composer.js';
+import type { RuntimeConfigDocument } from '@zhin.js/plugin-runtime';
 import type { IsolatedPluginRuntimePort } from './isolation.js';
 import type { ModuleRuntime } from './module-runtime.js';
 import { type PluginConfigResolver, type RootResourceInstaller } from './plugin-scope-assembler.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhin.js/runtime",
-  "version": "1.1.0",
+  "version": "1.1.2",
   "description": "Static Plugin graph, generation transaction and HMR Root runtime for Zhin.js",
   "type": "module",
   "main": "./lib/index.js",
@@ -18,23 +18,24 @@
   "dependencies": {
     "ajv": "8.18.0",
     "semver": "7.8.5",
-    "@zhin.js/plugin-runtime": "1.1.9",
-    "@zhin.js/feature-kit": "1.1.0"
+    "@zhin.js/feature-kit": "1.1.2",
+    "@zhin.js/plugin-runtime": "1.1.11"
   },
   "devDependencies": {
     "@types/node": "^26.1.2",
+    "tsx": "^4.23.1",
     "typescript": "^6.0.3",
-    "@zhin.js/adapter": "1.1.12",
-    "@zhin.js/agent-feature": "1.1.0",
-    "@zhin.js/command": "1.1.0",
-    "@zhin.js/component": "1.1.0",
-    "@zhin.js/layout": "1.1.0",
-    "@zhin.js/mcp-feature": "1.1.0",
-    "@zhin.js/middleware": "1.1.0",
-    "@zhin.js/skill": "1.1.0",
-    "@zhin.js/prompt-section": "1.1.0",
-    "@zhin.js/tool": "1.1.0",
-    "@zhin.js/page": "1.1.0"
+    "@zhin.js/adapter": "1.1.15",
+    "@zhin.js/agent-feature": "1.1.2",
+    "@zhin.js/command": "1.1.2",
+    "@zhin.js/component": "1.1.2",
+    "@zhin.js/layout": "1.1.2",
+    "@zhin.js/mcp-feature": "1.1.2",
+    "@zhin.js/middleware": "1.1.2",
+    "@zhin.js/page": "1.1.2",
+    "@zhin.js/prompt-section": "1.1.2",
+    "@zhin.js/skill": "1.1.2",
+    "@zhin.js/tool": "1.1.2"
   },
   "repository": {
     "type": "git",

package/lib/config-document.d.ts

@@ -1,19 +0,0 @@
-import type { RuntimeConfigDocument } from './config-composer.js';
-import type { ConfigPatch } from './config-patch-planner.js';
-export interface ConfigDocumentSnapshot {
-    readonly document: RuntimeConfigDocument;
-    readonly revision: string;
-}
-/** A prepared write is inert until the generation handoff activates it. */
-export interface PreparedConfigDocument {
-    readonly document: RuntimeConfigDocument;
-    commit(): Promise<ConfigDocumentSnapshot>;
-    rollback(): Promise<void>;
-}
-export interface ConfigDocumentPort {
-    read(): Promise<ConfigDocumentSnapshot>;
-    prepare(current: ConfigDocumentSnapshot, patches: readonly ConfigPatch[]): Promise<PreparedConfigDocument>;
-}
-export declare class ConfigDocumentDivergenceError extends Error {
-    constructor();
-}

package/lib/config-document.js

@@ -1,6 +0,0 @@
-export class ConfigDocumentDivergenceError extends Error {
-    constructor() {
-        super('ConfigDocument adapter candidate differs from the validated Runtime candidate');
-        this.name = 'ConfigDocumentDivergenceError';
-    }
-}