@zhin.js/runtime 1.1.2 → 1.1.4

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

@@ -1,4 +1,4 @@
-import { DisposeStack, Scope, type Dispose, type FeatureId, type GenerationHandoff, type GenerationAdmissionGate, type GenerationHandoffRegistry, type PluginId, type PluginNodeSnapshot, type SetupCapabilityRegistration, type TokenId } from '@zhin.js/plugin-runtime';
+import { DisposeStack, Scope, type Dispose, type FeatureId, type GenerationHandoff, type GenerationAdmissionGate, type GenerationHandoffRegistry, type RuntimeSnapshot, type PluginId, type PluginNodeSnapshot, type SetupCapabilityRegistration, type TokenId } from '@zhin.js/plugin-runtime';
 import { type RuntimeEnvironment } from './environment.js';
 import { type EnvironmentLayers } from './environment-store.js';
 import type { ModuleRuntime } from './module-runtime.js';
@@ -10,6 +10,8 @@ export type PluginConfigResolver = (node: PluginGraphNode) => unknown;
 export interface RootResourceContext {
     /** Exact shadow generation being assembled; never inferred from a latest snapshot. */
     readonly generation: number;
+    /** Exact projected candidate, available during handoff activation, never the committed previous generation. */
+    readonly readCandidateSnapshot?: () => RuntimeSnapshot;
     readonly signal: AbortSignal;
     readonly resources: Scope;
     readonly lifecycle: DisposeStack;
@@ -51,6 +53,7 @@ export declare class PluginScopeAssembler {
     setupTree(node: PluginGraphNode, signal: AbortSignal): Promise<void>;
     synchronizeTree(node: PluginGraphNode): void;
     createdScopeDisposers(): readonly (readonly [PluginId, Dispose])[];
+    bindCandidateSnapshot(snapshot: RuntimeSnapshot): void;
     generationHandoff(): GenerationHandoff | undefined;
     setupCapabilities(): readonly Readonly<SetupCapabilityRegistration>[];
     /** Root resources are process-owned; every Plugin Scope receives an owner-bound facade. */

package/lib/plugin-scope-assembler.js

@@ -21,6 +21,7 @@ export class PluginScopeAssembler {
     #handoffs = new GenerationHandoffStack();
     #admission = createGenerationAdmissionGate();
     #envStores;
+    #candidateSnapshot;
     #setupFeatureAliases = new Map();
     constructor(modules, configResolver, environment, primaryConfigDocument, generation, installResources, environmentLayers = {}, seed, isolation) {
         this.modules = modules;
@@ -71,6 +72,11 @@ export class PluginScopeAssembler {
             scope.provide(primaryConfigToken, config);
             await this.installResources?.({
                 generation: this.generation,
+                readCandidateSnapshot: () => {
+                    if (!this.#candidateSnapshot)
+                        throw new Error('Candidate snapshot is not projected yet');
+                    return this.#candidateSnapshot;
+                },
                 signal,
                 resources: scope,
                 lifecycle: scope.disposers,
@@ -206,6 +212,12 @@ export class PluginScopeAssembler {
             return [owner, () => scope.disposers.dispose()];
         });
     }
+    bindCandidateSnapshot(snapshot) {
+        if (snapshot.generation !== this.generation || this.#candidateSnapshot) {
+            throw new Error('Candidate snapshot does not match this Plugin assembly');
+        }
+        this.#candidateSnapshot = snapshot;
+    }
     generationHandoff() {
         return this.#handoffs.seal();
     }

package/lib/root-runtime.js

@@ -1,3 +1,4 @@
+import { normalizeSourcePath } from './source-path.js';
 import { resolve } from 'node:path';
 import { isDeepStrictEqual } from 'node:util';
 import { DisposeStack, GenerationHandoffStack, RootController, ConfigDocumentDivergenceError, createSnapshotView, rootPluginId, } from '@zhin.js/plugin-runtime';
@@ -41,7 +42,7 @@ export class RootRuntime {
     #controller;
     #disabledPluginInstanceKeys;
     constructor(options) {
-        this.#projectRoot = resolve(options.projectRoot);
+        this.#projectRoot = normalizeSourcePath(options.projectRoot);
         this.#modules = options.modules;
         this.#environment = defineRuntimeEnvironment(options.environment);
         this.#environmentLayers = defineEnvironmentLayers(options.environmentVariables);
@@ -55,7 +56,7 @@ export class RootRuntime {
         this.#runtimeInputSources = new Set([
             ...(this.#configPort?.sources ?? []),
             ...(this.#environmentSource?.sources ?? []),
-        ].map((source) => resolve(source)));
+        ].map((source) => normalizeSourcePath(source)));
         this.#installResources = options.installResources;
         this.#isolation = options.isolation;
         this.#disabledPluginInstanceKeys = Object.freeze([...(options.disabledPluginInstanceKeys ?? [])]);
@@ -105,7 +106,7 @@ export class RootRuntime {
             modules: this.#modules,
             ownership: () => this.sourceOwnership,
             runtime: {
-                handlesSource: (source) => this.#runtimeInputSources.has(resolve(source)),
+                handlesSource: (source) => this.#runtimeInputSources.has(normalizeSourcePath(source)),
                 reload: async (plan) => {
                     const result = await this.#reloadPlan(plan);
                     return isProcessPlan(result) ? result : undefined;
@@ -139,7 +140,7 @@ export class RootRuntime {
             ? Object.freeze({
                 ...plan,
                 subtrees: collapseInvalidationSubtrees([...plan.subtrees, ...inputs.roots]),
-                fallbacks: Object.freeze(plan.fallbacks.filter((fallback) => !inputs.inputSources.has(resolve(fallback.source)))),
+                fallbacks: Object.freeze(plan.fallbacks.filter((fallback) => !inputs.inputSources.has(normalizeSourcePath(fallback.source)))),
             })
             : plan;
         let restart;
@@ -189,11 +190,11 @@ export class RootRuntime {
         return this.#controller.committed.state.model;
     }
     async #planRuntimeInputs(changed) {
-        const inputSources = new Set(changed.map((source) => resolve(source)).filter((source) => this.#runtimeInputSources.has(source)));
+        const inputSources = new Set(changed.map((source) => normalizeSourcePath(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 configChanged = this.#configPort?.sources?.some((source) => inputSources.has(normalizeSourcePath(source))) ?? false;
+        const environmentChanged = this.#environmentSource?.sources.some((source) => inputSources.has(normalizeSourcePath(source))) ?? false;
         const configSnapshot = configChanged ? await this.#configPort?.read() : undefined;
         const document = configSnapshot?.document ?? requireConfigDocument(this.#configDocument);
         const environmentLayers = environmentChanged && this.#environmentSource
@@ -210,7 +211,7 @@ export class RootRuntime {
         if (inputPlan.hostKeys.length > 0) {
             return Object.freeze({
                 kind: 'process',
-                changed: Object.freeze([...changed].map((source) => resolve(source))),
+                changed: Object.freeze([...changed].map((source) => normalizeSourcePath(source))),
                 reasons: Object.freeze(inputPlan.hostKeys.map((key) => `Host configuration changed: ${key}`)),
             });
         }
@@ -263,7 +264,7 @@ 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)))
+            if (this.#runtimeInputSources.has(normalizeSourcePath(source)))
                 return true;
             const records = this.sourceOwnership.recordsFor(source);
             return records.length > 0 && records.every((record) => record.role === 'plugin' || record.role === 'schema');
@@ -519,6 +520,7 @@ class GenerationAssembler {
             }
             const state = projected.state;
             const snapshot = createSnapshotView(this.generation, state);
+            this.#plugins.bindCandidateSnapshot(snapshot);
             const ownership = SourceOwnershipIndex.fromGeneration(this.graph, snapshot, this.#featureIdsByPackageRoot);
             const assets = GenerationAssets.create(this.#plugins.createdScopeDisposers(), this.#projectionDisposers);
             return prepareRuntimeGeneration({

package/lib/source-ownership.d.ts

@@ -17,6 +17,7 @@ export declare class SourceOwnershipIndex {
     addPackageRoot(packageRoot: string, owner: PluginId): void;
     recordsFor(source: string): readonly SourceOwnershipRecord[];
     ownersForPath(source: string): readonly PluginId[];
+    moduleSources(): readonly string[];
     watchRoots(): readonly ModuleWatchRoot[];
     addWatchRoot(root: ModuleWatchRoot): void;
 }

package/lib/source-ownership.js

@@ -1,3 +1,4 @@
+import { normalizeSourcePath } from './source-path.js';
 import { isAbsolute, relative, resolve } from 'node:path';
 export class SourceOwnershipIndex {
     #records = new Map();
@@ -92,11 +93,17 @@ export class SourceOwnershipIndex {
         }
         return Object.freeze([...owners]);
     }
+    moduleSources() {
+        return Object.freeze([...this.#records.entries()]
+            .filter(([, records]) => records.some((record) => (record.role === 'plugin' || record.role === 'feature' || record.role === 'capability')))
+            .map(([source]) => source)
+            .sort());
+    }
     watchRoots() {
         return Object.freeze([...this.#watchRoots.values()]);
     }
     addWatchRoot(root) {
-        const normalized = resolve(root.root);
+        const normalized = normalizeSourcePath(root.root);
         this.#watchRoots.set(normalized, Object.freeze({ ...root, root: normalized }));
     }
 }
@@ -106,7 +113,7 @@ function visitPlugin(node, visit) {
         visitPlugin(child, visit);
 }
 function normalizeSource(source) {
-    return resolve(source);
+    return normalizeSourcePath(source);
 }
 function contains(packageRoot, source) {
     const path = relative(packageRoot, source);

package/lib/source-path.d.ts

@@ -0,0 +1,4 @@
+/** Keep file events and scanned sources in the same physical path namespace.
+ * Resolve the nearest existing parent for unlink events and newly added files.
+ */
+export declare function normalizeSourcePath(source: string): string;

package/lib/source-path.js

@@ -0,0 +1,25 @@
+import { realpathSync } from 'node:fs';
+import { basename, dirname, join, resolve } from 'node:path';
+/** Keep file events and scanned sources in the same physical path namespace.
+ * Resolve the nearest existing parent for unlink events and newly added files.
+ */
+export function normalizeSourcePath(source) {
+    const absolute = resolve(source);
+    let parent = absolute;
+    const suffix = [];
+    for (;;) {
+        try {
+            return join(realpathSync(parent), ...suffix);
+        }
+        catch (error) {
+            const code = error.code;
+            if (code !== 'ENOENT' && code !== 'ENOTDIR')
+                throw error;
+            const next = dirname(parent);
+            if (next === parent)
+                return absolute;
+            suffix.unshift(basename(parent));
+            parent = next;
+        }
+    }
+}

package/lib/subtree-generation-preparer.js

@@ -82,6 +82,7 @@ export class SubtreeGenerationPreparer {
                 projectionDisposers.set(feature, dispose);
             }
             const snapshot = createSnapshotView(current.generation + 1, projected.state);
+            plugins.bindCandidateSnapshot(snapshot);
             const ownership = SourceOwnershipIndex.fromGeneration(this.graph, snapshot, this.model.featureIdsByPackageRoot);
             const replacements = new Map(plugins.createdScopeDisposers());
             // Local prepare still commits a complete immutable generation. The

package/lib/topology-generation-preparer.js

@@ -89,6 +89,7 @@ export class TopologyGenerationPreparer {
                 projectionDisposers.set(feature, dispose);
             }
             const snapshot = createSnapshotView(current.generation + 1, projected.state);
+            plugins.bindCandidateSnapshot(snapshot);
             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);

package/lib/typescript-specifier-remap.d.ts

@@ -1,3 +1,8 @@
+interface ResolveResult {
+    readonly url: string;
+    readonly shortCircuit?: boolean;
+    readonly format?: string;
+}
 /**
  * ESM resolve hook: when a relative/absolute `.js` specifier fails and a
  * sibling `.ts` / `.tsx` exists, rewrite to that source file.
@@ -10,14 +15,7 @@ export declare function resolve(specifier: string, context: {
     parentURL?: string;
 }, nextResolve: (specifier: string, context: {
     parentURL?: string;
-}) => Promise<{
-    url: string;
-    shortCircuit?: boolean;
-    format?: string;
-}>): Promise<{
-    url: string;
-    shortCircuit?: boolean;
-    format?: string;
-}>;
+}) => Promise<ResolveResult>): Promise<ResolveResult>;
 /** Register once for the current process (safe to call from CLI / RootHost). */
 export declare function ensureTypeScriptSpecifierRemap(): void;
+export {};

package/lib/typescript-specifier-remap.js

@@ -1,6 +1,6 @@
 import { access } from 'node:fs/promises';
 import { register } from 'node:module';
-import { sep } from 'node:path';
+import { isAbsolute, sep } from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 /**
  * ESM resolve hook: when a relative/absolute `.js` specifier fails and a
@@ -11,8 +11,9 @@ import { fileURLToPath, pathToFileURL } from 'node:url';
  * remap missing `.js` → `.ts` the way `tsc`/tsx do.
  */
 export async function resolve(specifier, context, nextResolve) {
+    let resolved;
     try {
-        return await nextResolve(specifier, context);
+        resolved = await nextResolve(specifier, context);
     }
     catch (error) {
         if (!shouldTryTypeScript(specifier, error))
@@ -20,8 +21,9 @@ export async function resolve(specifier, context, nextResolve) {
         const candidate = await firstExistingTypeScript(specifier, context.parentURL);
         if (!candidate)
             throw error;
-        return nextResolve(candidate, context);
+        resolved = await nextResolve(candidate, context);
     }
+    return inheritGenerationRevision(specifier, context.parentURL, resolved);
 }
 let registered = false;
 /** Register once for the current process (safe to call from CLI / RootHost). */
@@ -39,6 +41,29 @@ function shouldTryTypeScript(specifier, error) {
         return false;
     return /\.[cm]?js$/u.test(specifier) || specifier.endsWith('.jsx');
 }
+function inheritGenerationRevision(specifier, parentURL, resolved) {
+    if (!parentURL || !isLocalSpecifier(specifier) || !resolved.url.startsWith('file:')) {
+        return resolved;
+    }
+    let revision;
+    try {
+        revision = new URL(parentURL).searchParams.get('zhin-generation');
+    }
+    catch {
+        return resolved;
+    }
+    if (revision === null)
+        return resolved;
+    const url = new URL(resolved.url);
+    url.searchParams.set('zhin-generation', revision);
+    return { ...resolved, url: url.href };
+}
+function isLocalSpecifier(specifier) {
+    return specifier.startsWith('.')
+        || specifier.startsWith('#')
+        || specifier.startsWith('file:')
+        || isAbsolute(specifier);
+}
 async function firstExistingTypeScript(specifier, parentURL) {
     const resolvedJs = resolveAgainstParent(specifier, parentURL);
     if (!resolvedJs)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhin.js/runtime",
-  "version": "1.1.2",
+  "version": "1.1.4",
   "description": "Static Plugin graph, generation transaction and HMR Root runtime for Zhin.js",
   "type": "module",
   "main": "./lib/index.js",
@@ -17,25 +17,27 @@
   ],
   "dependencies": {
     "ajv": "8.18.0",
+    "es-module-lexer": "2.3.1",
+    "import-meta-resolve": "4.2.0",
     "semver": "7.8.5",
-    "@zhin.js/feature-kit": "1.1.2",
-    "@zhin.js/plugin-runtime": "1.1.11"
+    "@zhin.js/plugin-runtime": "1.1.11",
+    "@zhin.js/feature-kit": "1.1.2"
   },
   "devDependencies": {
     "@types/node": "^26.1.2",
     "tsx": "^4.23.1",
     "typescript": "^6.0.3",
-    "@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/adapter": "1.1.16",
+    "@zhin.js/agent-feature": "1.1.3",
+    "@zhin.js/command": "1.1.4",
+    "@zhin.js/component": "1.1.3",
+    "@zhin.js/mcp-feature": "1.1.3",
+    "@zhin.js/layout": "1.1.3",
+    "@zhin.js/page": "1.1.3",
+    "@zhin.js/middleware": "1.1.3",
     "@zhin.js/prompt-section": "1.1.2",
-    "@zhin.js/skill": "1.1.2",
-    "@zhin.js/tool": "1.1.2"
+    "@zhin.js/skill": "1.1.3",
+    "@zhin.js/tool": "1.1.3"
   },
   "repository": {
     "type": "git",