@zhin.js/runtime 1.0.1 → 1.0.2

package/lib/environment-store.js

@@ -201,14 +201,19 @@ function expandString(input, lookup, onMissing) {
         if (start < 0)
             break;
         let j = start + 2;
-        if (j >= input.length || !isEnvKeyStart(input[j])) {
+        const first = input[j];
+        if (first === undefined || !isEnvKeyStart(first)) {
             out += input.slice(i, start + 1);
             i = start + 1;
             continue;
         }
         j += 1;
-        while (j < input.length && isEnvKeyChar(input[j]))
+        while (j < input.length) {
+            const character = input[j];
+            if (character === undefined || !isEnvKeyChar(character))
+                break;
             j += 1;
+        }
         const key = input.slice(start + 2, j);
         let fallback;
         if (input[j] === ':' && (input[j + 1] === '-' || input[j + 1] === '=')) {

package/lib/index.d.ts

@@ -12,6 +12,7 @@ export * from './module-runtime.js';
 export * from './native-development-runtime.js';
 export * from './node-discovery-host.js';
 export * from './package-resolver.js';
+export * from './primary-config.js';
 export * from './project-graph.js';
 export * from './process-restart.js';
 export * from './restart-boundary.js';

package/lib/index.js

@@ -12,6 +12,7 @@ export * from './module-runtime.js';
 export * from './native-development-runtime.js';
 export * from './node-discovery-host.js';
 export * from './package-resolver.js';
+export * from './primary-config.js';
 export * from './project-graph.js';
 export * from './process-restart.js';
 export * from './restart-boundary.js';

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

@@ -4,11 +4,14 @@ import { type EnvironmentLayers } from './environment-store.js';
 import type { ModuleRuntime } from './module-runtime.js';
 import type { PluginGraphNode } from './project-graph.js';
 import type { IsolatedPluginRuntimePort } from './isolation.js';
+import { type PrimaryConfig } from './primary-config.js';
+import type { RuntimeConfigDocument } from './config-composer.js';
 export type PluginConfigResolver = (node: PluginGraphNode) => unknown;
 export interface RootResourceContext {
     readonly resources: Scope;
     readonly lifecycle: DisposeStack;
     readonly handoff: GenerationHandoffRegistry;
+    readonly config: PrimaryConfig;
 }
 export type RootResourceInstaller = (context: RootResourceContext) => void | Promise<void>;
 export interface PluginAssemblySeed {
@@ -23,13 +26,14 @@ export declare class PluginScopeAssembler {
     private readonly modules;
     private readonly configResolver;
     private readonly environment;
+    private readonly primaryConfigDocument;
     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, installResources?: RootResourceInstaller | undefined, environmentLayers?: EnvironmentLayers, seed?: PluginAssemblySeed, isolation?: IsolatedPluginRuntimePort | undefined);
+    constructor(modules: ModuleRuntime, configResolver: PluginConfigResolver, environment: RuntimeEnvironment, primaryConfigDocument: RuntimeConfigDocument, installResources?: RootResourceInstaller | undefined, environmentLayers?: EnvironmentLayers, seed?: PluginAssemblySeed, isolation?: IsolatedPluginRuntimePort | undefined);
     removeSubtrees(roots: readonly PluginId[]): void;
     setupTree(node: PluginGraphNode): Promise<void>;
     synchronizeTree(node: PluginGraphNode): void;

package/lib/plugin-scope-assembler.js

@@ -2,11 +2,13 @@ import { resolve } from 'node:path';
 import { GenerationHandoffStack, Scope, rootPluginId, } from '@zhin.js/plugin-runtime';
 import { runtimeEnvironmentToken } from './environment.js';
 import { EnvStoreFactory, envStoreToken, } from './environment-store.js';
+import { createPrimaryConfig, primaryConfigToken, } from './primary-config.js';
 /** Assembles Plugin setup into mutable shadow maps without publishing them. */
 export class PluginScopeAssembler {
     modules;
     configResolver;
     environment;
+    primaryConfigDocument;
     installResources;
     isolation;
     scopes;
@@ -16,10 +18,11 @@ export class PluginScopeAssembler {
     #created = [];
     #handoffs = new GenerationHandoffStack();
     #envStores;
-    constructor(modules, configResolver, environment, installResources, environmentLayers = {}, seed, isolation) {
+    constructor(modules, configResolver, environment, primaryConfigDocument, installResources, environmentLayers = {}, seed, isolation) {
         this.modules = modules;
         this.configResolver = configResolver;
         this.environment = environment;
+        this.primaryConfigDocument = primaryConfigDocument;
         this.installResources = installResources;
         this.isolation = isolation;
         this.#envStores = new EnvStoreFactory(environment, environmentLayers);
@@ -49,13 +52,17 @@ export class PluginScopeAssembler {
         this.scopes.set(node.id, scope);
         this.#created.push(node.id);
         // Every owner shadows the inherited EnvStore with its exact overlay view.
-        scope.provide(envStoreToken, this.#envStores.create(node.id));
+        const environment = this.#envStores.create(node.id);
+        scope.provide(envStoreToken, environment);
         if (!node.parent) {
             scope.provide(runtimeEnvironmentToken, this.environment);
+            const config = createPrimaryConfig(this.primaryConfigDocument, environment);
+            scope.provide(primaryConfigToken, config);
             await this.installResources?.({
                 resources: scope,
                 lifecycle: scope.disposers,
                 handoff: this.#handoffs,
+                config,
             });
         }
         const config = Object.freeze(this.configResolver(node) ?? {});

package/lib/primary-config.d.ts

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

package/lib/primary-config.js

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

package/lib/root-runtime.js

@@ -118,7 +118,7 @@ export class RootRuntime {
                 restart = new RestartBoundaryPlanner().plan(this.#model.graph, inspected.graph, plan.changed);
                 if (restart)
                     return undefined;
-                prepared = await new TopologyGenerationPreparer(this.#modules, this.#model, inspected.graph, inspected.configResolver, this.#environment, this.#installResources, this.#environmentLayers, this.#isolation).prepare(current);
+                prepared = await new TopologyGenerationPreparer(this.#modules, this.#model, inspected.graph, inspected.configResolver, inspected.primaryConfigDocument, this.#environment, this.#installResources, this.#environmentLayers, this.#isolation).prepare(current);
             }
             else if (plan.subtrees.length === 0 && plan.slots.length > 0 && this.#model) {
                 prepared = await new SlotGenerationPreparer(this.#modules, this.#model)
@@ -168,12 +168,19 @@ export class RootRuntime {
     async #inspectProject() {
         const resolver = await NodePackageResolver.create(this.#projectRoot);
         const graph = await new ProjectGraphService(resolver).inspect(this.#projectRoot);
-        const configResolver = this.#configResolver
-            ? this.#configResolver
-            : await new ConfigComposer()
-                .compose(graph, this.#configDocument)
-                .then((composed) => this.#configViewResolver(composed.views));
-        return { graph, configResolver };
+        if (this.#configResolver) {
+            return {
+                graph,
+                configResolver: this.#configResolver,
+                primaryConfigDocument: Object.freeze({}),
+            };
+        }
+        const composed = await new ConfigComposer().compose(graph, this.#configDocument);
+        return {
+            graph,
+            configResolver: this.#configViewResolver(composed.views),
+            primaryConfigDocument: composed.document,
+        };
     }
     #configViewResolver(views) {
         const env = createEnvStore(rootPluginId(), this.#environment, this.#environmentLayers);
@@ -217,8 +224,12 @@ export class RootRuntime {
             const inspected = {
                 graph,
                 configResolver: this.#configViewResolver(planned.views),
+                primaryConfigDocument: planned.document,
             };
-            if (this.#model && !planned.roots.includes(rootPluginId())) {
+            // Root resources may consume any Primary Config section. Reinstall them
+            // when present so a committed patch cannot leave Host services on the
+            // previous generation's document.
+            if (!this.#installResources && this.#model && !planned.roots.includes(rootPluginId())) {
                 prepared = await this.#prepareSubtrees(current, inspected, planned.roots);
             }
             else {
@@ -237,14 +248,14 @@ export class RootRuntime {
         return snapshot;
     }
     #prepareInspected(current, inspected) {
-        const assembler = new GenerationAssembler(inspected.graph, this.#modules, inspected.configResolver, current.generation + 1, this.#environment, this.#installResources, this.#environmentLayers, this.#isolation);
+        const assembler = new GenerationAssembler(inspected.graph, this.#modules, inspected.configResolver, inspected.primaryConfigDocument, current.generation + 1, this.#environment, this.#installResources, this.#environmentLayers, this.#isolation);
         return assembler.prepare();
     }
     async #prepareSubtrees(current, inspected, roots) {
         if (!this.#model)
             return this.#prepareInspected(current, inspected);
         try {
-            return await new SubtreeGenerationPreparer(this.#modules, this.#model, inspected.graph, inspected.configResolver, this.#environment, this.#installResources, this.#environmentLayers, this.#isolation).prepare(current, roots);
+            return await new SubtreeGenerationPreparer(this.#modules, this.#model, inspected.graph, inspected.configResolver, inspected.primaryConfigDocument, this.#environment, this.#installResources, this.#environmentLayers, this.#isolation).prepare(current, roots);
         }
         catch (error) {
             if (!(error instanceof SubtreeTopologyChangedError))
@@ -292,6 +303,7 @@ class GenerationAssembler {
     graph;
     modules;
     configResolver;
+    primaryConfigDocument;
     generation;
     environment;
     installResources;
@@ -304,17 +316,18 @@ class GenerationAssembler {
     #projectionDisposers = [];
     #host;
     #plugins;
-    constructor(graph, modules, configResolver, generation, environment, installResources, environmentLayers = {}, isolation) {
+    constructor(graph, modules, configResolver, primaryConfigDocument, generation, environment, installResources, environmentLayers = {}, isolation) {
         this.graph = graph;
         this.modules = modules;
         this.configResolver = configResolver;
+        this.primaryConfigDocument = primaryConfigDocument;
         this.generation = generation;
         this.environment = environment;
         this.installResources = installResources;
         this.environmentLayers = environmentLayers;
         this.isolation = isolation;
         this.#host = new NodeDiscoveryHost(modules);
-        this.#plugins = new PluginScopeAssembler(modules, configResolver, environment, installResources, environmentLayers, undefined, isolation);
+        this.#plugins = new PluginScopeAssembler(modules, configResolver, environment, primaryConfigDocument, installResources, environmentLayers, undefined, isolation);
     }
     async prepare() {
         try {

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

@@ -1,6 +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 { IsolatedPluginRuntimePort } from './isolation.js';
 import type { ModuleRuntime } from './module-runtime.js';
 import { type PluginConfigResolver, type RootResourceInstaller } from './plugin-scope-assembler.js';
@@ -15,10 +16,11 @@ export declare class SubtreeGenerationPreparer {
     private readonly model;
     private readonly graph;
     private readonly configResolver;
+    private readonly primaryConfigDocument;
     private readonly environment;
     private readonly installResources?;
     private readonly environmentLayers;
     private readonly isolation?;
-    constructor(modules: ModuleRuntime, model: RuntimeGenerationModel, graph: ProjectGraph, configResolver: PluginConfigResolver, environment: RuntimeEnvironment, installResources?: RootResourceInstaller | undefined, environmentLayers?: EnvironmentLayers, isolation?: IsolatedPluginRuntimePort | undefined);
+    constructor(modules: ModuleRuntime, model: RuntimeGenerationModel, graph: ProjectGraph, configResolver: PluginConfigResolver, primaryConfigDocument: RuntimeConfigDocument, environment: RuntimeEnvironment, installResources?: RootResourceInstaller | undefined, environmentLayers?: EnvironmentLayers, isolation?: IsolatedPluginRuntimePort | undefined);
     prepare(current: RuntimeSnapshot, roots: readonly PluginId[]): Promise<PreparedRuntimeGeneration>;
 }

package/lib/subtree-generation-preparer.js

@@ -16,15 +16,17 @@ export class SubtreeGenerationPreparer {
     model;
     graph;
     configResolver;
+    primaryConfigDocument;
     environment;
     installResources;
     environmentLayers;
     isolation;
-    constructor(modules, model, graph, configResolver, environment, installResources, environmentLayers = {}, isolation) {
+    constructor(modules, model, graph, configResolver, primaryConfigDocument, environment, installResources, environmentLayers = {}, isolation) {
         this.modules = modules;
         this.model = model;
         this.graph = graph;
         this.configResolver = configResolver;
+        this.primaryConfigDocument = primaryConfigDocument;
         this.environment = environment;
         this.installResources = installResources;
         this.environmentLayers = environmentLayers;
@@ -33,7 +35,7 @@ export class SubtreeGenerationPreparer {
     async prepare(current, roots) {
         const nodes = indexGraph(this.graph);
         assertCompatibleTopology(indexGraph(this.model.graph), nodes, roots);
-        const plugins = new PluginScopeAssembler(this.modules, this.configResolver, this.environment, this.installResources, this.environmentLayers, {
+        const plugins = new PluginScopeAssembler(this.modules, this.configResolver, this.environment, this.primaryConfigDocument, this.installResources, this.environmentLayers, {
             scopes: this.model.scopes,
             tree: current.tree,
             config: current.config,

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

@@ -1,6 +1,7 @@
 import { 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 { IsolatedPluginRuntimePort } from './isolation.js';
 import type { ModuleRuntime } from './module-runtime.js';
 import { type PluginConfigResolver, type RootResourceInstaller } from './plugin-scope-assembler.js';
@@ -13,10 +14,11 @@ export declare class TopologyGenerationPreparer {
     private readonly model;
     private readonly graph;
     private readonly configResolver;
+    private readonly primaryConfigDocument;
     private readonly environment;
     private readonly installResources?;
     private readonly environmentLayers;
     private readonly isolation?;
-    constructor(modules: ModuleRuntime, model: RuntimeGenerationModel, graph: ProjectGraph, configResolver: PluginConfigResolver, environment: RuntimeEnvironment, installResources?: RootResourceInstaller | undefined, environmentLayers?: EnvironmentLayers, isolation?: IsolatedPluginRuntimePort | undefined);
+    constructor(modules: ModuleRuntime, model: RuntimeGenerationModel, graph: ProjectGraph, configResolver: PluginConfigResolver, primaryConfigDocument: RuntimeConfigDocument, environment: RuntimeEnvironment, installResources?: RootResourceInstaller | undefined, environmentLayers?: EnvironmentLayers, isolation?: IsolatedPluginRuntimePort | undefined);
     prepare(current: RuntimeSnapshot): Promise<PreparedRuntimeGeneration | undefined>;
 }

package/lib/topology-generation-preparer.js

@@ -13,15 +13,17 @@ export class TopologyGenerationPreparer {
     model;
     graph;
     configResolver;
+    primaryConfigDocument;
     environment;
     installResources;
     environmentLayers;
     isolation;
-    constructor(modules, model, graph, configResolver, environment, installResources, environmentLayers = {}, isolation) {
+    constructor(modules, model, graph, configResolver, primaryConfigDocument, environment, installResources, environmentLayers = {}, isolation) {
         this.modules = modules;
         this.model = model;
         this.graph = graph;
         this.configResolver = configResolver;
+        this.primaryConfigDocument = primaryConfigDocument;
         this.environment = environment;
         this.installResources = installResources;
         this.environmentLayers = environmentLayers;
@@ -39,7 +41,7 @@ export class TopologyGenerationPreparer {
         if (!plan.changed)
             return undefined;
         const featureTopology = await this.#loadFeatureTopology(plan);
-        const plugins = new PluginScopeAssembler(this.modules, this.configResolver, this.environment, this.installResources, this.environmentLayers, {
+        const plugins = new PluginScopeAssembler(this.modules, this.configResolver, this.environment, this.primaryConfigDocument, this.installResources, this.environmentLayers, {
             scopes: this.model.scopes,
             tree: current.tree,
             config: current.config,

package/package.json

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