@zhin.js/runtime 1.0.12 → 1.0.14

package/lib/config-composer.d.ts

@@ -1,5 +1,7 @@
 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 {

package/lib/config-composer.js

@@ -1,6 +1,18 @@
 import { readFile } from 'node:fs/promises';
 import { join } from 'node:path';
 import Ajv2020 from 'ajv/dist/2020.js';
+import hostConfigSchema from './host-config-schema.json' with { type: 'json' };
+function deepFreeze(value) {
+    if (value && typeof value === 'object' && !Object.isFrozen(value)) {
+        for (const nested of Object.values(value))
+            deepFreeze(nested);
+        Object.freeze(value);
+    }
+    return value;
+}
+const HOST_CONFIG_SCHEMA = deepFreeze(hostConfigSchema);
+/** Host configuration keys consumed by Runtime composition and Host installers. */
+export const HOST_CONFIG_KEYS = Object.freeze(Object.keys(HOST_CONFIG_SCHEMA.properties));
 export class ConfigSchemaCollisionError extends Error {
     plugin;
     instanceKey;
@@ -43,6 +55,7 @@ export class ConfigComposer {
             type: 'object',
             additionalProperties: false,
             properties: {
+                ...HOST_CONFIG_SCHEMA.properties,
                 plugin: withDefault(rootOwn),
                 plugins: {
                     type: 'object',
@@ -50,45 +63,10 @@ export class ConfigComposer {
                     default: {},
                     properties: Object.fromEntries(childSchemas.map(([key, schema]) => [key, withDefault(schema)])),
                 },
-                http: Object.freeze({
-                    type: 'object',
-                    additionalProperties: true,
-                }),
-                database: Object.freeze({
-                    type: 'object',
-                    additionalProperties: true,
-                }),
-                ai: Object.freeze({
-                    type: 'object',
-                    additionalProperties: true,
-                }),
-                mcp: Object.freeze({
-                    type: 'object',
-                    additionalProperties: true,
-                }),
-                a2a: Object.freeze({
-                    type: 'object',
-                    additionalProperties: true,
-                }),
-                speech: Object.freeze({
-                    type: 'object',
-                    additionalProperties: true,
-                }),
-                htmlRenderer: Object.freeze({
-                    type: 'object',
-                    additionalProperties: true,
-                }),
-                assistant: Object.freeze({
-                    type: 'object',
-                    additionalProperties: true,
-                }),
-                log_level: Object.freeze({
-                    type: ['string', 'number'],
-                }),
             },
         });
         const document = structuredClone(input);
-        const validate = new Ajv2020({
+        const ajv = new Ajv2020({
             allErrors: true,
             useDefaults: true,
             strict: true,
@@ -96,7 +74,9 @@ export class ConfigComposer {
             // 不触发 allowUnionTypes）；保留此项是面向未来插件 schema 可能出现的
             // anyOf/oneOf 标量 union，避免届时 Ajv strict 模式直接报错。
             allowUnionTypes: true,
-        }).compile(effectiveSchema);
+        });
+        ajv.addKeyword({ keyword: 'x-descriptionZh', schemaType: 'string' });
+        const validate = ajv.compile(effectiveSchema);
         if (!validate(document)) {
             throw new ConfigValidationError(formatErrors(validate.errors ?? []), source);
         }

package/lib/hmr-coordinator.d.ts

@@ -20,6 +20,6 @@ export declare class HmrCoordinator {
     private readonly options;
     constructor(options: HmrCoordinatorOptions);
     start(): Dispose;
-    stop(): void;
+    stop(): Promise<void>;
     enqueue(source: string): Promise<void>;
 }

package/lib/hmr-coordinator.js

@@ -5,12 +5,19 @@ export class HmrCoordinator {
     #waiters = [];
     #draining;
     #unwatch;
+    #closing = false;
+    #restartRequired = false;
+    #stopResult;
     constructor(options) {
         this.options = options;
     }
     start() {
         if (this.#unwatch)
             throw new Error('HmrCoordinator is already started');
+        if (this.#closing)
+            throw new Error('HmrCoordinator has been stopped');
+        if (this.#restartRequired)
+            throw new Error('HmrCoordinator requires a process restart');
         if (!this.options.modules.watch) {
             throw new Error('ModuleRuntime does not provide a file watcher');
         }
@@ -21,10 +28,23 @@ export class HmrCoordinator {
         return () => this.stop();
     }
     stop() {
+        if (this.#stopResult)
+            return this.#stopResult;
+        this.#closing = true;
         this.#unwatch?.();
         this.#unwatch = undefined;
+        this.#stopResult = (async () => {
+            await this.#draining;
+        })();
+        return this.#stopResult;
     }
     enqueue(source) {
+        if (this.#closing) {
+            return Promise.reject(new Error('HMR coordinator is stopping'));
+        }
+        if (this.#restartRequired) {
+            return Promise.reject(new Error('HMR coordinator requires a process restart'));
+        }
         this.#pending.add(source);
         const completed = new Promise((resolve, reject) => {
             this.#waiters.push({ resolve, reject });
@@ -50,14 +70,16 @@ export class HmrCoordinator {
                 this.#pending.clear();
                 const forcedRestart = changed.filter((source) => this.options.modules.requiresProcessRestart?.(source));
                 if (forcedRestart.length > 0) {
-                    await this.options.onRestartRequired(Object.freeze({
+                    this.#restartRequired = true;
+                    this.#pending.clear();
+                    this.#notifyRestart(Object.freeze({
                         kind: 'process',
                         changed: Object.freeze(changed),
                         reasons: Object.freeze([
                             `Module loader cannot safely invalidate: ${forcedRestart.join(', ')}`,
                         ]),
                     }));
-                    continue;
+                    break;
                 }
                 const dependencyPort = this.options.modules.affectedSources
                     ? {
@@ -65,11 +87,14 @@ export class HmrCoordinator {
                     }
                     : undefined;
                 const plan = new InvalidationPlanner(this.options.ownership(), dependencyPort).plan(changed);
-                await this.options.onPlan?.(plan);
                 if (plan.kind === 'process') {
-                    await this.options.onRestartRequired(plan);
-                    continue;
+                    this.#restartRequired = true;
+                    this.#pending.clear();
+                    this.#notifyPlan(plan);
+                    this.#notifyRestart(plan);
+                    break;
                 }
+                this.#notifyPlan(plan);
                 if (plan.kind === 'none')
                     continue;
                 const startedAt = performance.now();
@@ -77,15 +102,30 @@ export class HmrCoordinator {
                     await this.options.modules.invalidate?.(source);
                 }
                 const restart = await this.options.runtime.reload(plan);
-                if (restart)
-                    await this.options.onRestartRequired(restart);
+                if (restart) {
+                    this.#restartRequired = true;
+                    this.#pending.clear();
+                    this.#notifyRestart(restart);
+                    break;
+                }
                 else {
                     // reload resolves only after RootController has committed the new
                     // generation. Read ownership now so failed transactions never make
                     // newly discovered workspace packages observable to the watcher.
                     this.#syncWatchRoots();
                     const durationMs = Number((performance.now() - startedAt).toFixed(1));
-                    await this.options.onReload?.(plan, durationMs);
+                    try {
+                        await this.options.onReload?.(plan, durationMs);
+                    }
+                    catch (error) {
+                        // A projection/observer cannot change an already committed reload.
+                        try {
+                            await this.options.onError(error);
+                        }
+                        catch {
+                            // Diagnostic reporting is deliberately outside the outcome.
+                        }
+                    }
                 }
             }
             this.#resolveWaiters();
@@ -105,7 +145,7 @@ export class HmrCoordinator {
             this.#draining = undefined;
             // A source may arrive after the loop observed an empty queue but before
             // this promise settled. Keep its waiter attached to a fresh transaction.
-            if (this.#pending.size > 0)
+            if (!this.#closing && !this.#restartRequired && this.#pending.size > 0)
                 this.#ensureDrain();
         }
     }
@@ -120,4 +160,37 @@ export class HmrCoordinator {
     #syncWatchRoots() {
         this.options.modules.updateWatchRoots?.(this.options.ownership().watchRoots());
     }
+    #notifyRestart(plan) {
+        // Restart is a committed control outcome. Invoke the observer without
+        // awaiting it so a Process Host may await RootHost.stop() without waiting
+        // on the HMR drain that is currently delivering this notification.
+        try {
+            void Promise.resolve(this.options.onRestartRequired(plan)).catch((error) => {
+                this.#reportDiagnostic(error);
+            });
+        }
+        catch (error) {
+            this.#reportDiagnostic(error);
+        }
+    }
+    #notifyPlan(plan) {
+        if (!this.options.onPlan)
+            return;
+        try {
+            void Promise.resolve(this.options.onPlan(plan)).catch((error) => {
+                this.#reportDiagnostic(error);
+            });
+        }
+        catch (error) {
+            this.#reportDiagnostic(error);
+        }
+    }
+    #reportDiagnostic(error) {
+        try {
+            void Promise.resolve(this.options.onError(error)).catch(() => undefined);
+        }
+        catch {
+            // Diagnostic reporting cannot change an invalidation outcome.
+        }
+    }
 }

package/lib/host-config-schema.json

@@ -0,0 +1,123 @@
+{
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {
+        "http": { "type": "object", "additionalProperties": true, "description": "HTTP, Console, REST/RPC/SSE, and Webhook Host.", "x-descriptionZh": "HTTP、Console、REST/RPC/SSE 与 Webhook Host。" },
+        "database": { "type": "object", "additionalProperties": true, "description": "Database Host and dialect connection options.", "x-descriptionZh": "Database Host 与方言连接参数。" },
+        "ai": {
+            "type": "object",
+            "additionalProperties": true,
+            "description": "Providers, Agents, sessions, memory, tools, and execution security.",
+            "x-descriptionZh": "Provider、Agent、会话、记忆、工具与执行安全策略。",
+            "properties": {
+                "agent": {
+                    "type": "object",
+                    "additionalProperties": true,
+                    "description": "Agent execution, queueing, tool, and model policies.",
+                    "x-descriptionZh": "Agent 执行、排队、工具与模型策略。",
+                    "properties": {
+                        "inboundQueue": {
+                            "type": "object",
+                            "additionalProperties": true,
+                            "description": "Inbound turn queue policy.",
+                            "x-descriptionZh": "入站回合排队策略。",
+                            "properties": {
+                                "groupMode": {
+                                    "type": "string",
+                                    "enum": ["supersede", "fifo"],
+                                    "description": "Replace an older queued group turn, or process all turns in arrival order.",
+                                    "x-descriptionZh": "覆盖较早的群聊排队回合，或按到达顺序处理全部回合。"
+                                }
+                            }
+                        },
+                        "execSecurity": {
+                            "type": "string",
+                            "enum": ["deny", "allowlist", "full"],
+                            "description": "Shell command security boundary.",
+                            "x-descriptionZh": "Shell 命令安全边界。"
+                        },
+                        "execPreset": {
+                            "type": "string",
+                            "enum": ["readonly", "network", "development", "custom"],
+                            "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 命令的审批策略。" },
+                        "toolExecution": {
+                            "type": "string",
+                            "enum": ["parallel", "sequential", "tiered"],
+                            "description": "How tool calls in one model step are scheduled.",
+                            "x-descriptionZh": "同一模型步骤中的工具调用调度方式。"
+                        },
+                        "modelSizeHint": {
+                            "type": "string",
+                            "enum": ["", "small", "medium", "large"],
+                            "description": "Optional model-size hint; an empty string clears the hint.",
+                            "x-descriptionZh": "可选模型尺寸提示；空字符串表示清除提示。"
+                        },
+                        "promptCacheRetention": {
+                            "type": "string",
+                            "enum": ["in_memory", "24h"],
+                            "description": "Provider prompt-cache retention policy.",
+                            "x-descriptionZh": "Provider Prompt Cache 保留策略。"
+                        },
+                        "steeringMode": {
+                            "type": "string",
+                            "enum": ["one-at-a-time", "all"],
+                            "description": "Process steering messages one at a time or drain all pending messages together.",
+                            "x-descriptionZh": "逐条处理 Steering 消息，或一次取出全部待处理消息。"
+                        },
+                        "followUpMode": {
+                            "type": "string",
+                            "enum": ["one-at-a-time", "all"],
+                            "description": "Process follow-up messages one at a time or drain all pending messages together.",
+                            "x-descriptionZh": "逐条处理 Follow-up 消息，或一次取出全部待处理消息。"
+                        },
+                        "outputSchema": {
+                            "anyOf": [
+                                { "type": "boolean" },
+                                { "type": "string", "enum": ["segments"] },
+                                { "type": "object" }
+                            ],
+                            "description": "Structured final-output mode: false for text, true or segments for canonical message segments, or a custom JSON Schema object.",
+                            "x-descriptionZh": "结构化最终输出：false 表示文本，true 或 segments 表示规范消息段，也可传入自定义 JSON Schema 对象。"
+                        },
+                        "schedule": {
+                            "type": "object",
+                            "additionalProperties": true,
+                            "description": "Unattended Schedule execution policy.",
+                            "x-descriptionZh": "无人值守 Schedule 执行策略。",
+                            "properties": {
+                                "security": {
+                                    "type": "object",
+                                    "additionalProperties": true,
+                                    "description": "Schedule command security policy.",
+                                    "x-descriptionZh": "Schedule 命令安全策略。",
+                                    "properties": {
+                                        "execPreset": {
+                                            "type": "string",
+                                            "enum": ["readonly", "network"],
+                                            "description": "Schedule Jobs may use only the read-only or network preset.",
+                                            "x-descriptionZh": "Schedule Job 只能使用只读或网络预设。"
+                                        }
+                                    }
+                                }
+                            }
+                        }
+                    }
+                }
+            }
+        },
+        "mcp": { "type": "object", "additionalProperties": true, "description": "Expose Bot tools through an MCP Server.", "x-descriptionZh": "把 Bot 工具公开为 MCP Server。" },
+        "a2a": { "type": "object", "additionalProperties": true, "description": "A2A Agent Card, remote execution, and Workroom callbacks.", "x-descriptionZh": "A2A Agent Card、远程执行与 Workroom 回调。" },
+        "speech": { "type": "object", "additionalProperties": true, "description": "Speech-to-text and text-to-speech Host.", "x-descriptionZh": "语音识别与语音合成 Host。" },
+        "htmlRenderer": { "type": "object", "additionalProperties": true, "description": "HTML and image rendering options.", "x-descriptionZh": "HTML/图片渲染参数。" },
+        "assistant": { "type": "object", "additionalProperties": true, "description": "Scheduled jobs, event ingress, and failure notifications.", "x-descriptionZh": "调度任务、事件入口和失败通知。" },
+        "log_level": { "type": ["string", "number"], "description": "Runtime log level.", "x-descriptionZh": "Runtime 日志级别。" },
+        "plugin": { "type": "object", "description": "Root Plugin configuration; replaced by its project schema during composition.", "x-descriptionZh": "Root Plugin 配置；组合时由项目 Schema 替换。" }
+    }
+}

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

@@ -8,6 +8,8 @@ import { type PrimaryConfig } from './primary-config.js';
 import type { RuntimeConfigDocument } from './config-composer.js';
 export type PluginConfigResolver = (node: PluginGraphNode) => unknown;
 export interface RootResourceContext {
+    /** Exact shadow generation being assembled; never inferred from a latest snapshot. */
+    readonly generation: number;
     readonly signal: AbortSignal;
     readonly resources: Scope;
     readonly lifecycle: DisposeStack;
@@ -36,13 +38,14 @@ export declare class PluginScopeAssembler {
     private readonly configResolver;
     private readonly environment;
     private readonly primaryConfigDocument;
+    private readonly generation;
     private readonly installResources?;
     private readonly isolation?;
     readonly scopes: Map<PluginId, Scope>;
     readonly tree: Map<PluginId, PluginNodeSnapshot>;
     readonly config: Map<PluginId, unknown>;
     readonly resources: Map<PluginId, ReadonlyMap<TokenId, unknown>>;
-    constructor(modules: ModuleRuntime, configResolver: PluginConfigResolver, environment: RuntimeEnvironment, primaryConfigDocument: RuntimeConfigDocument, installResources?: RootResourceInstaller | undefined, environmentLayers?: EnvironmentLayers, seed?: PluginAssemblySeed, isolation?: IsolatedPluginRuntimePort | undefined);
+    constructor(modules: ModuleRuntime, configResolver: PluginConfigResolver, environment: RuntimeEnvironment, primaryConfigDocument: RuntimeConfigDocument, generation: number, installResources?: RootResourceInstaller | undefined, environmentLayers?: EnvironmentLayers, seed?: PluginAssemblySeed, isolation?: IsolatedPluginRuntimePort | undefined);
     removeSubtrees(roots: readonly PluginId[]): void;
     installSetupFeatureAliases(aliases: ReadonlyMap<string, FeatureId>): void;
     setupTree(node: PluginGraphNode, signal: AbortSignal): Promise<void>;

package/lib/plugin-scope-assembler.js

@@ -9,6 +9,7 @@ export class PluginScopeAssembler {
     configResolver;
     environment;
     primaryConfigDocument;
+    generation;
     installResources;
     isolation;
     scopes;
@@ -21,11 +22,12 @@ export class PluginScopeAssembler {
     #admission = createGenerationAdmissionGate();
     #envStores;
     #setupFeatureAliases = new Map();
-    constructor(modules, configResolver, environment, primaryConfigDocument, installResources, environmentLayers = {}, seed, isolation) {
+    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);
@@ -68,6 +70,7 @@ export class PluginScopeAssembler {
             const config = createPrimaryConfig(this.primaryConfigDocument, environment);
             scope.provide(primaryConfigToken, config);
             await this.installResources?.({
+                generation: this.generation,
                 signal,
                 resources: scope,
                 lifecycle: scope.disposers,

package/lib/root-runtime.d.ts

@@ -8,6 +8,7 @@ import type { IsolatedPluginRuntimePort } from './isolation.js';
 import type { ModuleRuntime } from './module-runtime.js';
 import { type PluginConfigResolver, type RootResourceInstaller } from './plugin-scope-assembler.js';
 import { HmrCoordinator, type HmrCoordinatorOptions } from './hmr-coordinator.js';
+import { type RuntimeGenerationState } from './runtime-generation.js';
 import { RootProcessRestartExecutor, type ProcessRestartAdapter } from './process-restart.js';
 import { SourceOwnershipIndex } from './source-ownership.js';
 export type { PluginConfigResolver, RootResourceContext, RootResourceInstaller, } from './plugin-scope-assembler.js';
@@ -27,7 +28,7 @@ export declare class RootRuntime {
     constructor(options: RootRuntimeOptions);
     get snapshot(): RuntimeSnapshot;
     get snapshots(): SnapshotReader;
-    onGenerationCommit(listener: GenerationCommitListener): () => void;
+    onGenerationCommit(listener: GenerationCommitListener<RuntimeGenerationState>): () => void;
     get sourceOwnership(): SourceOwnershipIndex;
     start(): Promise<RuntimeSnapshot>;
     reload(target?: PluginId | string): Promise<RuntimeSnapshot>;

package/lib/root-runtime.js

@@ -14,6 +14,7 @@ import { NodePackageResolver } from './package-resolver.js';
 import { PluginScopeAssembler, } from './plugin-scope-assembler.js';
 import { ProjectGraphService, } from './project-graph.js';
 import { HmrCoordinator } from './hmr-coordinator.js';
+import { prepareRuntimeGeneration, } from './runtime-generation.js';
 import { RootProcessRestartExecutor, } from './process-restart.js';
 import { SlotGenerationPreparer } from './slot-generation-preparer.js';
 import { capabilityDeltaFromSlots, capabilityDeltaIds, ConventionCapabilityDeltaResolver, filterCapabilityDelta, mergeCapabilityDeltas, } from './convention-capability-delta.js';
@@ -33,8 +34,6 @@ export class RootRuntime {
     #configDocument;
     #installResources;
     #isolation;
-    #ownership = SourceOwnershipIndex.empty();
-    #model;
     #configPatchTail = Promise.resolve();
     #stopResult;
     #controller;
@@ -51,7 +50,7 @@ export class RootRuntime {
             this.#configDocument = structuredClone(options.config ?? {});
         this.#installResources = options.installResources;
         this.#isolation = options.isolation;
-        this.#controller = new RootController(emptyState(), options.onControlError);
+        this.#controller = new RootController(emptyState(), options.onControlError, Object.freeze({ ownership: SourceOwnershipIndex.empty() }));
     }
     get snapshot() {
         return this.#controller.snapshot;
@@ -63,7 +62,7 @@ export class RootRuntime {
         return this.#controller.onGenerationCommit(listener);
     }
     get sourceOwnership() {
-        return this.#ownership;
+        return this.#controller.committed.state.ownership;
     }
     async start() {
         if (this.#configPort) {
@@ -71,21 +70,15 @@ export class RootRuntime {
             this.#configSnapshot = snapshot;
             this.#configDocument = structuredClone(snapshot.document);
         }
-        let prepared;
         const snapshot = await this.#controller.start(async (current, signal) => {
-            prepared = await this.#prepare(current, signal);
-            return prepared.generation;
+            return (await this.#prepare(current, signal)).generation;
         });
-        this.#accept(requirePrepared(prepared));
         return snapshot;
     }
     async reload(target = rootPluginId()) {
-        let prepared;
         const snapshot = await this.#controller.reload(target, async (current, signal) => {
-            prepared = await this.#prepare(current, signal);
-            return prepared.generation;
+            return (await this.#prepare(current, signal)).generation;
         });
-        this.#accept(requirePrepared(prepared));
         return snapshot;
     }
     patchConfig(patches) {
@@ -98,7 +91,7 @@ export class RootRuntime {
         return new HmrCoordinator({
             ...options,
             modules: this.#modules,
-            ownership: () => this.#ownership,
+            ownership: () => this.sourceOwnership,
             runtime: {
                 reload: async (plan) => {
                     const result = await this.#reloadPlan(plan);
@@ -125,9 +118,9 @@ export class RootRuntime {
         return result;
     }
     async #reloadPlan(plan) {
-        let prepared;
         let restart;
         const snapshot = await this.#controller.reload(plan.subtrees[0] ?? plan.slots[0] ?? rootPluginId(), async (current, signal) => {
+            let prepared;
             const resolved = await this.#resolveCapabilityDelta(current, plan);
             const effective = resolved.plan;
             if (this.#model && effective.manifestSources.length > 0) {
@@ -154,13 +147,10 @@ export class RootRuntime {
         });
         if (restart)
             return restart;
-        if (prepared)
-            this.#accept(prepared);
         return snapshot;
     }
-    #accept(prepared) {
-        this.#ownership = prepared.ownership;
-        this.#model = prepared.model;
+    get #model() {
+        return this.#controller.committed.state.model;
     }
     async #resolveCapabilityDelta(current, plan) {
         const known = capabilityDeltaFromSlots(current, plan.slots);
@@ -185,7 +175,7 @@ export class RootRuntime {
         if (plan.subtrees.length === 0 || plan.subtrees.includes(rootPluginId()))
             return false;
         return plan.changed.every((source) => {
-            const records = this.#ownership.recordsFor(source);
+            const records = this.sourceOwnership.recordsFor(source);
             return records.length > 0 && records.every((record) => record.role === 'plugin' || record.role === 'schema');
         });
     }
@@ -247,10 +237,10 @@ export class RootRuntime {
         await this.#refreshConfigDocument();
         const currentDocument = requireConfigDocument(this.#configDocument);
         let plan;
-        let prepared;
         let documentTransaction;
         let committedDocument;
         const snapshot = await this.#controller.reload(rootPluginId(), async (current, signal) => {
+            let prepared;
             signal.throwIfAborted();
             const resolver = await NodePackageResolver.create(this.#projectRoot);
             const graph = await new ProjectGraphService(resolver).inspect(this.#projectRoot);
@@ -305,8 +295,6 @@ export class RootRuntime {
             }
         });
         const completed = requireConfigPatchPlan(plan);
-        if (prepared)
-            this.#accept(prepared);
         this.#configDocument = completed.candidate;
         if (committedDocument)
             this.#configSnapshot = committedDocument;
@@ -406,7 +394,7 @@ class GenerationAssembler {
         this.environmentLayers = environmentLayers;
         this.isolation = isolation;
         this.#host = new NodeDiscoveryHost(modules);
-        this.#plugins = new PluginScopeAssembler(modules, configResolver, environment, primaryConfigDocument, installResources, environmentLayers, undefined, isolation);
+        this.#plugins = new PluginScopeAssembler(modules, configResolver, environment, primaryConfigDocument, generation, installResources, environmentLayers, undefined, isolation);
     }
     async prepare(signal) {
         signal.throwIfAborted();
@@ -426,25 +414,21 @@ class GenerationAssembler {
             const snapshot = createSnapshotView(this.generation, state);
             const ownership = SourceOwnershipIndex.fromGeneration(this.graph, snapshot, this.#featureIdsByPackageRoot);
             const assets = GenerationAssets.create(this.#plugins.createdScopeDisposers(), this.#projectionDisposers);
-            return {
-                generation: {
-                    snapshot: state,
-                    dispose: () => assets.dispose(),
-                    handoff: composeGenerationHandoffs(this.#plugins.generationHandoff(), projected.handoff),
-                },
-                ownership,
-                model: {
-                    graph: this.graph,
-                    providers: new Map(this.#catalog.values().map((provider) => [provider.id, provider])),
-                    rootsByFeature: new Map([...this.#rootsByFeature].map(([feature, roots]) => [
-                        feature,
-                        Object.freeze([...roots]),
-                    ])),
-                    featureIdsByPackageRoot: new Map(this.#featureIdsByPackageRoot),
-                    scopes: new Map(this.#plugins.scopes),
-                    assets,
-                },
-            };
+            return prepareRuntimeGeneration({
+                snapshot: state,
+                dispose: () => assets.dispose(),
+                handoff: composeGenerationHandoffs(this.#plugins.generationHandoff(), projected.handoff),
+            }, ownership, {
+                graph: this.graph,
+                providers: new Map(this.#catalog.values().map((provider) => [provider.id, provider])),
+                rootsByFeature: new Map([...this.#rootsByFeature].map(([feature, roots]) => [
+                    feature,
+                    Object.freeze([...roots]),
+                ])),
+                featureIdsByPackageRoot: new Map(this.#featureIdsByPackageRoot),
+                scopes: new Map(this.#plugins.scopes),
+                assets,
+            });
         }
         catch (error) {
             await disposePreparedParts(this.#plugins.createdScopeDisposers().map(([, dispose]) => dispose), [...this.#projectionDisposers.values()], error);
@@ -507,11 +491,6 @@ function emptyState() {
         projections: new Map(),
     };
 }
-function requirePrepared(prepared) {
-    if (!prepared)
-        throw new Error('RootController committed without a prepared generation');
-    return prepared;
-}
 function isProcessPlan(value) {
     return 'kind' in value && value.kind === 'process';
 }

package/lib/runtime-generation.d.ts

@@ -11,8 +11,12 @@ export interface RuntimeGenerationModel {
     readonly scopes: ReadonlyMap<PluginId, Scope>;
     readonly assets: GenerationAssets;
 }
-export interface PreparedRuntimeGeneration {
-    readonly generation: PreparedGeneration;
+/** Sidecar state that must never be observed from a different generation. */
+export interface RuntimeGenerationState {
     readonly ownership: SourceOwnershipIndex;
-    readonly model: RuntimeGenerationModel;
+    readonly model?: RuntimeGenerationModel;
+}
+export interface PreparedRuntimeGeneration {
+    readonly generation: PreparedGeneration<RuntimeGenerationState>;
 }
+export declare function prepareRuntimeGeneration(generation: PreparedGeneration, ownership: SourceOwnershipIndex, model: RuntimeGenerationModel): PreparedRuntimeGeneration;

package/lib/runtime-generation.js

@@ -1 +1,8 @@
-export {};
+export function prepareRuntimeGeneration(generation, ownership, model) {
+    return Object.freeze({
+        generation: Object.freeze({
+            ...generation,
+            state: Object.freeze({ ownership, model }),
+        }),
+    });
+}

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

@@ -1,6 +1,6 @@
 import { type CapabilityId, type RuntimeSnapshot } from '@zhin.js/plugin-runtime';
 import type { ModuleRuntime } from './module-runtime.js';
-import type { PreparedRuntimeGeneration, RuntimeGenerationModel } from './runtime-generation.js';
+import { type PreparedRuntimeGeneration, type RuntimeGenerationModel } from './runtime-generation.js';
 import { type CapabilityDelta } from './convention-capability-delta.js';
 export declare class SlotGenerationPreparer {
     private readonly modules;

package/lib/slot-generation-preparer.js

@@ -2,6 +2,7 @@ import { DisposeStack, createSnapshotView, } from '@zhin.js/plugin-runtime';
 import { FeatureDiscovery } from '@zhin.js/feature-kit';
 import { FeatureProjector, composeGenerationHandoffs } from './feature-projector.js';
 import { NodeDiscoveryHost } from './node-discovery-host.js';
+import { prepareRuntimeGeneration, } from './runtime-generation.js';
 import { SourceOwnershipIndex } from './source-ownership.js';
 import { capabilityDeltaFromSlots, } from './convention-capability-delta.js';
 export class SlotGenerationPreparer {
@@ -48,15 +49,11 @@ export class SlotGenerationPreparer {
             const snapshot = createSnapshotView(current.generation + 1, projected.state);
             const ownership = SourceOwnershipIndex.fromGeneration(this.model.graph, snapshot, this.model.featureIdsByPackageRoot);
             const assets = this.model.assets.replaceProjections(selectedByFeature.keys(), projected.disposers);
-            return {
-                generation: {
-                    snapshot: projected.state,
-                    dispose: () => assets.dispose(),
-                    handoff: composeGenerationHandoffs(projected.handoff),
-                },
-                ownership,
-                model: { ...this.model, assets },
-            };
+            return prepareRuntimeGeneration({
+                snapshot: projected.state,
+                dispose: () => assets.dispose(),
+                handoff: composeGenerationHandoffs(projected.handoff),
+            }, ownership, { ...this.model, assets });
         }
         catch (error) {
             await disposeProjections(projected.disposers.values(), error);

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

@@ -6,7 +6,7 @@ import type { IsolatedPluginRuntimePort } from './isolation.js';
 import type { ModuleRuntime } from './module-runtime.js';
 import { type PluginConfigResolver, type RootResourceInstaller } from './plugin-scope-assembler.js';
 import type { ProjectGraph } from './project-graph.js';
-import type { PreparedRuntimeGeneration, RuntimeGenerationModel } from './runtime-generation.js';
+import { type PreparedRuntimeGeneration, type RuntimeGenerationModel } from './runtime-generation.js';
 export declare class SubtreeTopologyChangedError extends Error {
     constructor(message: string);
 }

package/lib/subtree-generation-preparer.js

@@ -3,6 +3,7 @@ import { FeatureDiscovery } from '@zhin.js/feature-kit';
 import { FeatureProjector, composeGenerationHandoffs } from './feature-projector.js';
 import { NodeDiscoveryHost } from './node-discovery-host.js';
 import { PluginScopeAssembler, } from './plugin-scope-assembler.js';
+import { prepareRuntimeGeneration, } from './runtime-generation.js';
 import { SourceOwnershipIndex } from './source-ownership.js';
 import { addCapabilitySlot, featureSetupAliases, mergeSetupCapabilities, } from './setup-capabilities.js';
 export class SubtreeTopologyChangedError extends Error {
@@ -37,7 +38,7 @@ export class SubtreeGenerationPreparer {
         signal.throwIfAborted();
         const nodes = indexGraph(this.graph);
         assertCompatibleTopology(indexGraph(this.model.graph), nodes, roots);
-        const plugins = new PluginScopeAssembler(this.modules, this.configResolver, this.environment, this.primaryConfigDocument, this.installResources, this.environmentLayers, {
+        const plugins = new PluginScopeAssembler(this.modules, this.configResolver, this.environment, this.primaryConfigDocument, current.generation + 1, this.installResources, this.environmentLayers, {
             scopes: this.model.scopes,
             tree: current.tree,
             config: current.config,
@@ -86,20 +87,16 @@ export class SubtreeGenerationPreparer {
             // Local prepare still commits a complete immutable generation. The
             // replacement map controls lifetime ownership, not snapshot granularity.
             const assets = this.model.assets.replaceScopes([...nodes.keys()], replacements, projectionDisposers);
-            return {
-                generation: {
-                    snapshot: projected.state,
-                    dispose: () => assets.dispose(),
-                    handoff: composeGenerationHandoffs(plugins.generationHandoff(), projected.handoff),
-                },
-                ownership,
-                model: {
-                    ...this.model,
-                    graph: this.graph,
-                    scopes: new Map(plugins.scopes),
-                    assets,
-                },
-            };
+            return prepareRuntimeGeneration({
+                snapshot: projected.state,
+                dispose: () => assets.dispose(),
+                handoff: composeGenerationHandoffs(plugins.generationHandoff(), projected.handoff),
+            }, ownership, {
+                ...this.model,
+                graph: this.graph,
+                scopes: new Map(plugins.scopes),
+                assets,
+            });
         }
         catch (error) {
             await rollback(plugins.createdScopeDisposers().map(([, dispose]) => dispose), [...projectionDisposers.values()], error);

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

@@ -6,7 +6,7 @@ import type { IsolatedPluginRuntimePort } from './isolation.js';
 import type { ModuleRuntime } from './module-runtime.js';
 import { type PluginConfigResolver, type RootResourceInstaller } from './plugin-scope-assembler.js';
 import type { ProjectGraph } from './project-graph.js';
-import type { PreparedRuntimeGeneration, RuntimeGenerationModel } from './runtime-generation.js';
+import { type PreparedRuntimeGeneration, type RuntimeGenerationModel } from './runtime-generation.js';
 import { type CapabilityDelta } from './convention-capability-delta.js';
 /** Runtime-local invalidation to commit alongside an ABI-safe manifest change. */
 export interface TopologyRuntimeDelta {

package/lib/topology-generation-preparer.js

@@ -5,6 +5,7 @@ import { FeatureCatalog, FeatureDiscovery, } from '@zhin.js/feature-kit';
 import { FeatureProjector, composeGenerationHandoffs } from './feature-projector.js';
 import { NodeDiscoveryHost } from './node-discovery-host.js';
 import { PluginScopeAssembler, } from './plugin-scope-assembler.js';
+import { prepareRuntimeGeneration, } from './runtime-generation.js';
 import { SourceOwnershipIndex } from './source-ownership.js';
 import { capabilityDeltaFromSlots, capabilityDeltaIds, } from './convention-capability-delta.js';
 import { addCapabilitySlot, featureSetupAliases, mergeSetupCapabilities, } from './setup-capabilities.js';
@@ -46,7 +47,7 @@ export class TopologyGenerationPreparer {
         if (!plan.changed && subtreeRoots.length === 0 && selected.size === 0)
             return undefined;
         const featureTopology = await this.#loadFeatureTopology(plan);
-        const plugins = new PluginScopeAssembler(this.modules, this.configResolver, this.environment, this.primaryConfigDocument, this.installResources, this.environmentLayers, {
+        const plugins = new PluginScopeAssembler(this.modules, this.configResolver, this.environment, this.primaryConfigDocument, current.generation + 1, this.installResources, this.environmentLayers, {
             scopes: this.model.scopes,
             tree: current.tree,
             config: current.config,
@@ -91,22 +92,18 @@ export class TopologyGenerationPreparer {
             const ownership = SourceOwnershipIndex.fromGeneration(this.graph, snapshot, featureTopology.featureIdsByPackageRoot);
             const replacements = new Map(plugins.createdScopeDisposers());
             const assets = this.model.assets.replaceScopes(graphOrder(this.graph), replacements, projectionDisposers);
-            return {
-                generation: {
-                    snapshot: projected.state,
-                    dispose: () => assets.dispose(),
-                    handoff: composeGenerationHandoffs(plugins.generationHandoff(), projected.handoff),
-                },
-                ownership,
-                model: {
-                    graph: this.graph,
-                    providers: featureTopology.providers,
-                    rootsByFeature: featureTopology.rootsByFeature,
-                    featureIdsByPackageRoot: featureTopology.featureIdsByPackageRoot,
-                    scopes: new Map(plugins.scopes),
-                    assets,
-                },
-            };
+            return prepareRuntimeGeneration({
+                snapshot: projected.state,
+                dispose: () => assets.dispose(),
+                handoff: composeGenerationHandoffs(plugins.generationHandoff(), projected.handoff),
+            }, ownership, {
+                graph: this.graph,
+                providers: featureTopology.providers,
+                rootsByFeature: featureTopology.rootsByFeature,
+                featureIdsByPackageRoot: featureTopology.featureIdsByPackageRoot,
+                scopes: new Map(plugins.scopes),
+                assets,
+            });
         }
         catch (error) {
             await rollback(plugins.createdScopeDisposers().map(([, dispose]) => dispose), [...projectionDisposers.values()], error);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhin.js/runtime",
-  "version": "1.0.12",
+  "version": "1.0.14",
   "description": "Static Plugin graph, generation transaction and HMR Root runtime for Zhin.js",
   "type": "module",
   "main": "./lib/index.js",
@@ -18,22 +18,23 @@
   "dependencies": {
     "ajv": "8.18.0",
     "semver": "7.8.5",
-    "@zhin.js/feature-kit": "1.0.11",
-    "@zhin.js/plugin-runtime": "1.1.6"
+    "@zhin.js/plugin-runtime": "1.1.8",
+    "@zhin.js/feature-kit": "1.0.13"
   },
   "devDependencies": {
     "@types/node": "^26.1.2",
     "typescript": "^6.0.3",
-    "@zhin.js/adapter": "1.1.10",
-    "@zhin.js/agent-feature": "1.0.11",
-    "@zhin.js/command": "1.0.14",
-    "@zhin.js/component": "1.0.11",
-    "@zhin.js/layout": "1.0.11",
-    "@zhin.js/mcp-feature": "1.0.11",
-    "@zhin.js/middleware": "1.0.11",
-    "@zhin.js/page": "1.0.11",
-    "@zhin.js/skill": "1.0.11",
-    "@zhin.js/tool": "1.0.11"
+    "@zhin.js/agent-feature": "1.0.13",
+    "@zhin.js/adapter": "1.2.1",
+    "@zhin.js/command": "1.0.16",
+    "@zhin.js/component": "1.0.13",
+    "@zhin.js/layout": "1.0.13",
+    "@zhin.js/mcp-feature": "1.0.13",
+    "@zhin.js/middleware": "1.0.13",
+    "@zhin.js/prompt-section": "0.0.1",
+    "@zhin.js/skill": "1.0.13",
+    "@zhin.js/page": "1.0.13",
+    "@zhin.js/tool": "1.0.13"
   },
   "repository": {
     "type": "git",