@zhin.js/runtime 1.0.0

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

@@ -0,0 +1,24 @@
+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 { 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';
+export declare class SubtreeTopologyChangedError extends Error {
+    constructor(message: string);
+}
+/** Replaces selected Plugin forests while retaining all other Scope lifetimes. */
+export declare class SubtreeGenerationPreparer {
+    private readonly modules;
+    private readonly model;
+    private readonly graph;
+    private readonly configResolver;
+    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);
+    prepare(current: RuntimeSnapshot, roots: readonly PluginId[]): Promise<PreparedRuntimeGeneration>;
+}

package/lib/subtree-generation-preparer.js

@@ -0,0 +1,152 @@
+import { DisposeStack, createSnapshotView, rootPluginId, } 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 { PluginScopeAssembler, } from './plugin-scope-assembler.js';
+import { SourceOwnershipIndex } from './source-ownership.js';
+export class SubtreeTopologyChangedError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'SubtreeTopologyChangedError';
+    }
+}
+/** Replaces selected Plugin forests while retaining all other Scope lifetimes. */
+export class SubtreeGenerationPreparer {
+    modules;
+    model;
+    graph;
+    configResolver;
+    environment;
+    installResources;
+    environmentLayers;
+    isolation;
+    constructor(modules, model, graph, configResolver, environment, installResources, environmentLayers = {}, isolation) {
+        this.modules = modules;
+        this.model = model;
+        this.graph = graph;
+        this.configResolver = configResolver;
+        this.environment = environment;
+        this.installResources = installResources;
+        this.environmentLayers = environmentLayers;
+        this.isolation = isolation;
+    }
+    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, {
+            scopes: this.model.scopes,
+            tree: current.tree,
+            config: current.config,
+            resources: current.resources,
+        }, this.isolation);
+        plugins.removeSubtrees(roots);
+        const projectionDisposers = [];
+        try {
+            for (const root of roots) {
+                const node = nodes.get(root);
+                if (!node)
+                    throw new SubtreeTopologyChangedError(`Missing subtree root: ${root}`);
+                await plugins.setupTree(node);
+            }
+            const capabilities = new Map(current.capabilities);
+            for (const [id, slot] of capabilities) {
+                if (roots.some((root) => isWithin(slot.owner, root)))
+                    capabilities.delete(id);
+            }
+            const discovery = new FeatureDiscovery(new NodeDiscoveryHost(this.modules));
+            for (const provider of this.model.providers.values()) {
+                const affectedRoots = (this.model.rootsByFeature.get(provider.id) ?? [])
+                    .filter((root) => roots.some((owner) => isWithin(root.owner, owner)));
+                if (affectedRoots.length === 0)
+                    continue;
+                const slots = await discovery.discover(provider, affectedRoots);
+                for (const slot of slots)
+                    capabilities.set(slot.id, slot);
+            }
+            const projected = await new FeatureProjector(this.model.providers.values()).project(current.generation + 1, {
+                root: current.root,
+                tree: plugins.tree,
+                config: plugins.config,
+                resources: plugins.resources,
+                capabilities,
+            });
+            projectionDisposers.push(...projected.disposers);
+            const snapshot = createSnapshotView(current.generation + 1, projected.state);
+            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
+            // 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,
+                },
+            };
+        }
+        catch (error) {
+            await rollback(plugins.createdScopeDisposers().map(([, dispose]) => dispose), projectionDisposers, error);
+            throw error;
+        }
+    }
+}
+function indexGraph(graph) {
+    const result = new Map();
+    const visit = (node) => {
+        result.set(node.id, node);
+        for (const child of node.children)
+            visit(child);
+    };
+    visit(graph.root);
+    return result;
+}
+function assertCompatibleTopology(previousNodes, nextNodes, roots) {
+    if (roots.includes(rootPluginId())) {
+        throw new SubtreeTopologyChangedError('Root changes require a full generation');
+    }
+    if (previousNodes.size !== nextNodes.size) {
+        throw new SubtreeTopologyChangedError('Plugin tree size changed');
+    }
+    for (const [id, previous] of previousNodes) {
+        const next = nextNodes.get(id);
+        if (!next
+            || next.parent !== previous.parent
+            || next.instanceKey !== previous.instanceKey
+            || next.package.root !== previous.package.root
+            || next.package.name !== previous.package.name
+            || !sameValues(next.children.map((child) => child.id), previous.children.map((child) => child.id))
+            || !sameValues(featureRoots(next), featureRoots(previous))) {
+            throw new SubtreeTopologyChangedError(`Plugin topology changed at ${id}`);
+        }
+    }
+}
+function featureRoots(node) {
+    return node.features.map((feature) => feature.package.root);
+}
+function sameValues(left, right) {
+    return left.length === right.length && left.every((value, index) => value === right[index]);
+}
+function isWithin(plugin, root) {
+    return plugin === root || plugin.startsWith(`${root}/`);
+}
+async function rollback(scopeDisposers, projectionDisposers, prepareError) {
+    const disposers = new DisposeStack();
+    for (const dispose of scopeDisposers)
+        disposers.add(dispose);
+    for (const dispose of projectionDisposers)
+        disposers.add(dispose);
+    try {
+        await disposers.dispose();
+    }
+    catch (disposeError) {
+        throw new AggregateError([prepareError, disposeError], 'Subtree generation prepare and rollback both failed', { cause: disposeError });
+    }
+}

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

@@ -0,0 +1,22 @@
+import { type RuntimeSnapshot } from '@zhin.js/plugin-runtime';
+import type { RuntimeEnvironment } from './environment.js';
+import type { EnvironmentLayers } 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';
+import type { ProjectGraph } from './project-graph.js';
+import type { PreparedRuntimeGeneration, RuntimeGenerationModel } from './runtime-generation.js';
+/** Prepares manifest topology changes without rebuilding stable Plugin Scopes. */
+export declare class TopologyGenerationPreparer {
+    #private;
+    private readonly modules;
+    private readonly model;
+    private readonly graph;
+    private readonly configResolver;
+    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);
+    prepare(current: RuntimeSnapshot): Promise<PreparedRuntimeGeneration | undefined>;
+}

package/lib/topology-generation-preparer.js

@@ -0,0 +1,249 @@
+import { resolve } from 'node:path';
+import { isDeepStrictEqual } from 'node:util';
+import { DisposeStack, createSnapshotView, } from '@zhin.js/plugin-runtime';
+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 { SourceOwnershipIndex } from './source-ownership.js';
+import { TopologyTransactionPlanner, collapseRoots, graphNodes, graphOrder, isWithin, } from './topology-transaction.js';
+/** Prepares manifest topology changes without rebuilding stable Plugin Scopes. */
+export class TopologyGenerationPreparer {
+    modules;
+    model;
+    graph;
+    configResolver;
+    environment;
+    installResources;
+    environmentLayers;
+    isolation;
+    constructor(modules, model, graph, configResolver, environment, installResources, environmentLayers = {}, isolation) {
+        this.modules = modules;
+        this.model = model;
+        this.graph = graph;
+        this.configResolver = configResolver;
+        this.environment = environment;
+        this.installResources = installResources;
+        this.environmentLayers = environmentLayers;
+        this.isolation = isolation;
+    }
+    async prepare(current) {
+        const planned = new TopologyTransactionPlanner().plan(this.model.graph, this.graph);
+        const nextNodes = graphNodes(this.graph);
+        const configReplacements = changedConfigRoots(current, nextNodes, this.configResolver);
+        const replacedPluginRoots = collapseRoots([
+            ...planned.replacedPluginRoots,
+            ...configReplacements,
+        ]);
+        const plan = withReplacements(planned, replacedPluginRoots);
+        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, {
+            scopes: this.model.scopes,
+            tree: current.tree,
+            config: current.config,
+            resources: current.resources,
+        }, this.isolation);
+        const setupRoots = collapseRoots([
+            ...plan.addedPluginRoots,
+            ...plan.replacedPluginRoots,
+        ]);
+        const removalRoots = collapseRoots([
+            ...plan.removedPluginRoots,
+            ...plan.replacedPluginRoots,
+        ]);
+        plugins.removeSubtrees(removalRoots);
+        const projectionDisposers = [];
+        try {
+            for (const root of setupRoots) {
+                const node = nextNodes.get(root);
+                if (!node)
+                    throw new Error(`Missing topology setup root: ${root}`);
+                await plugins.setupTree(node);
+            }
+            // Retained parents still need a new immutable children view after add,
+            // remove, move, or reorder operations.
+            plugins.synchronizeTree(this.graph.root);
+            const capabilities = await this.#prepareCapabilities(current, plan, setupRoots, featureTopology);
+            const projected = await new FeatureProjector(featureTopology.providers.values()).project(current.generation + 1, {
+                root: current.root,
+                tree: plugins.tree,
+                config: plugins.config,
+                resources: plugins.resources,
+                capabilities,
+            });
+            projectionDisposers.push(...projected.disposers);
+            const snapshot = createSnapshotView(current.generation + 1, projected.state);
+            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,
+                },
+            };
+        }
+        catch (error) {
+            await rollback(plugins.createdScopeDisposers().map(([, dispose]) => dispose), projectionDisposers, error);
+            throw error;
+        }
+    }
+    async #loadFeatureTopology(plan) {
+        const catalog = new FeatureCatalog();
+        const providers = new Map();
+        const rootsByFeature = new Map();
+        const featureIdsByPackageRoot = new Map();
+        const loadedByPackageRoot = new Map();
+        for (const node of graphNodes(this.graph).values()) {
+            for (const requirement of node.features) {
+                const packageRoot = resolve(requirement.package.root);
+                let provider = loadedByPackageRoot.get(packageRoot);
+                if (!provider) {
+                    const previousId = this.model.featureIdsByPackageRoot.get(packageRoot);
+                    provider = !plan.reloadedFeaturePackages.has(packageRoot) && previousId
+                        ? this.model.providers.get(previousId)
+                        : undefined;
+                    if (!provider)
+                        provider = await loadProvider(this.modules, requirement.package);
+                    loadedByPackageRoot.set(packageRoot, provider);
+                    featureIdsByPackageRoot.set(packageRoot, provider.id);
+                    catalog.add(provider);
+                    providers.set(provider.id, provider);
+                }
+                const roots = rootsByFeature.get(provider.id) ?? [];
+                roots.push({ owner: node.id, packageRoot: node.package.root });
+                rootsByFeature.set(provider.id, roots);
+            }
+        }
+        return {
+            providers: new Map(providers),
+            rootsByFeature: new Map([...rootsByFeature].map(([feature, roots]) => [feature, Object.freeze(roots)])),
+            featureIdsByPackageRoot: new Map(featureIdsByPackageRoot),
+        };
+    }
+    async #prepareCapabilities(current, plan, setupRoots, topology) {
+        const nextOwners = new Set(graphNodes(this.graph).keys());
+        const mounted = mountedFeatures(topology);
+        const refresh = new Set();
+        for (const [feature, roots] of topology.rootsByFeature) {
+            for (const root of roots) {
+                if (setupRoots.some((owner) => isWithin(root.owner, owner))) {
+                    refresh.add(ownerFeatureKey(root.owner, feature));
+                }
+            }
+        }
+        for (const mount of plan.addedFeatures) {
+            const feature = topology.featureIdsByPackageRoot.get(mount.packageRoot);
+            if (feature)
+                refresh.add(ownerFeatureKey(mount.owner, feature));
+        }
+        for (const mount of featureMountsForReload(this.graph, plan.reloadedFeaturePackages)) {
+            const feature = topology.featureIdsByPackageRoot.get(mount.packageRoot);
+            if (feature)
+                refresh.add(ownerFeatureKey(mount.owner, feature));
+        }
+        for (const mount of plan.removedFeatures) {
+            const previousFeature = this.model.featureIdsByPackageRoot.get(mount.packageRoot);
+            if (previousFeature)
+                refresh.add(ownerFeatureKey(mount.owner, previousFeature));
+        }
+        const capabilities = new Map(current.capabilities);
+        for (const [id, slot] of capabilities) {
+            const key = ownerFeatureKey(slot.owner, slot.feature);
+            if (!nextOwners.has(slot.owner) || !mounted.has(key) || refresh.has(key)) {
+                capabilities.delete(id);
+            }
+        }
+        const discovery = new FeatureDiscovery(new NodeDiscoveryHost(this.modules));
+        for (const [feature, roots] of topology.rootsByFeature) {
+            const selected = roots.filter((root) => refresh.has(ownerFeatureKey(root.owner, feature)));
+            if (selected.length === 0)
+                continue;
+            const provider = topology.providers.get(feature);
+            if (!provider)
+                throw new Error(`Missing Feature provider for ${feature}`);
+            for (const slot of await discovery.discover(provider, selected)) {
+                capabilities.set(slot.id, slot);
+            }
+        }
+        return capabilities;
+    }
+}
+async function loadProvider(modules, pkg) {
+    const manifest = pkg.packageJson.zhin;
+    const module = await modules.load(resolve(pkg.root, manifest.entry));
+    const provider = module.default;
+    if (!provider || provider.protocol !== 1) {
+        throw new TypeError(`${pkg.name} does not default-export a Feature provider`);
+    }
+    return provider;
+}
+function changedConfigRoots(current, nextNodes, configResolver) {
+    const changed = [];
+    for (const [id, node] of nextNodes) {
+        if (!current.tree.has(id))
+            continue;
+        if (!isDeepStrictEqual(current.config.get(id), configResolver(node) ?? {}))
+            changed.push(id);
+    }
+    return collapseRoots(changed);
+}
+function withReplacements(plan, replacedPluginRoots) {
+    if (sameValues(plan.replacedPluginRoots, replacedPluginRoots))
+        return plan;
+    return Object.freeze({
+        ...plan,
+        replacedPluginRoots,
+        changed: plan.changed || replacedPluginRoots.length > 0,
+    });
+}
+function mountedFeatures(topology) {
+    const mounted = new Set();
+    for (const [feature, roots] of topology.rootsByFeature) {
+        for (const root of roots)
+            mounted.add(ownerFeatureKey(root.owner, feature));
+    }
+    return mounted;
+}
+function featureMountsForReload(graph, packageRoots) {
+    const mounts = [];
+    for (const node of graphNodes(graph).values()) {
+        for (const requirement of node.features) {
+            const packageRoot = resolve(requirement.package.root);
+            if (packageRoots.has(packageRoot))
+                mounts.push({ owner: node.id, packageRoot });
+        }
+    }
+    return mounts;
+}
+function ownerFeatureKey(owner, feature) {
+    return `${owner}\0${feature}`;
+}
+function sameValues(left, right) {
+    return left.length === right.length && left.every((value, index) => value === right[index]);
+}
+async function rollback(scopeDisposers, projectionDisposers, prepareError) {
+    const disposers = new DisposeStack();
+    for (const dispose of scopeDisposers)
+        disposers.add(dispose);
+    for (const dispose of projectionDisposers)
+        disposers.add(dispose);
+    try {
+        await disposers.dispose();
+    }
+    catch (disposeError) {
+        throw new AggregateError([prepareError, disposeError], 'Topology generation prepare and rollback both failed', { cause: disposeError });
+    }
+}

package/lib/topology-transaction.d.ts

@@ -0,0 +1,26 @@
+import type { PluginId } from '@zhin.js/plugin-runtime';
+import type { PluginGraphNode, ProjectGraph } from './project-graph.js';
+export interface FeatureMount {
+    readonly owner: PluginId;
+    readonly packageRoot: string;
+}
+export interface TopologyTransactionPlan {
+    readonly addedPluginRoots: readonly PluginId[];
+    readonly removedPluginRoots: readonly PluginId[];
+    readonly replacedPluginRoots: readonly PluginId[];
+    readonly addedFeatures: readonly FeatureMount[];
+    readonly removedFeatures: readonly FeatureMount[];
+    readonly reloadedFeaturePackages: ReadonlySet<string>;
+    readonly treeChanged: boolean;
+    readonly featureOrderChanged: boolean;
+    readonly changed: boolean;
+}
+/** Compiles two resolved graphs into the smallest safe topology transaction. */
+export declare class TopologyTransactionPlanner {
+    plan(previous: ProjectGraph, next: ProjectGraph): TopologyTransactionPlan;
+}
+export declare function graphNodes(graph: ProjectGraph): ReadonlyMap<PluginId, PluginGraphNode>;
+export declare function graphOrder(graph: ProjectGraph): readonly PluginId[];
+export declare function featureMounts(graph: ProjectGraph): readonly FeatureMount[];
+export declare function isWithin(plugin: PluginId, root: PluginId): boolean;
+export declare function collapseRoots(values: readonly PluginId[]): readonly PluginId[];

package/lib/topology-transaction.js

@@ -0,0 +1,142 @@
+import { resolve } from 'node:path';
+/** Compiles two resolved graphs into the smallest safe topology transaction. */
+export class TopologyTransactionPlanner {
+    plan(previous, next) {
+        const previousNodes = indexGraph(previous);
+        const nextNodes = indexGraph(next);
+        const added = [...nextNodes.keys()].filter((id) => !previousNodes.has(id));
+        const removed = [...previousNodes.keys()].filter((id) => !nextNodes.has(id));
+        const replaced = [...nextNodes].flatMap(([id, node]) => {
+            const old = previousNodes.get(id);
+            return old && scopeContractChanged(old, node) ? [id] : [];
+        });
+        const addedPluginRoots = collapseRoots(added);
+        const removedPluginRoots = collapseRoots(removed);
+        const replacedPluginRoots = collapseRoots(replaced);
+        const previousFeatures = featureMounts(previous);
+        const nextFeatures = featureMounts(next);
+        const addedFeatures = difference(nextFeatures, previousFeatures);
+        const removedFeatures = difference(previousFeatures, nextFeatures);
+        const reloadedFeaturePackages = changedFeaturePackages(previous, next);
+        const treeChanged = childOrderChanged(previousNodes, nextNodes);
+        const featureOrderChanged = !sameValues(previousFeatures.map(featureMountKey), nextFeatures.map(featureMountKey));
+        const changed = (addedPluginRoots.length > 0
+            || removedPluginRoots.length > 0
+            || replacedPluginRoots.length > 0
+            || addedFeatures.length > 0
+            || removedFeatures.length > 0
+            || reloadedFeaturePackages.size > 0
+            || treeChanged
+            || featureOrderChanged);
+        return Object.freeze({
+            addedPluginRoots,
+            removedPluginRoots,
+            replacedPluginRoots,
+            addedFeatures,
+            removedFeatures,
+            reloadedFeaturePackages,
+            treeChanged,
+            featureOrderChanged,
+            changed,
+        });
+    }
+}
+export function graphNodes(graph) {
+    return indexGraph(graph);
+}
+export function graphOrder(graph) {
+    return Object.freeze([...indexGraph(graph).keys()]);
+}
+export function featureMounts(graph) {
+    const mounts = [];
+    for (const node of indexGraph(graph).values()) {
+        for (const feature of node.features) {
+            mounts.push(Object.freeze({
+                owner: node.id,
+                packageRoot: resolve(feature.package.root),
+            }));
+        }
+    }
+    return Object.freeze(mounts);
+}
+export function isWithin(plugin, root) {
+    return plugin === root || plugin.startsWith(`${root}/`);
+}
+export function collapseRoots(values) {
+    const sorted = [...new Set(values)].sort((left, right) => left.length - right.length);
+    const roots = [];
+    for (const candidate of sorted) {
+        if (!roots.some((root) => isWithin(candidate, root)))
+            roots.push(candidate);
+    }
+    return Object.freeze(roots);
+}
+function indexGraph(graph) {
+    const nodes = new Map();
+    const visit = (node) => {
+        nodes.set(node.id, node);
+        for (const child of node.children)
+            visit(child);
+    };
+    visit(graph.root);
+    return nodes;
+}
+function scopeContractChanged(previous, next) {
+    const previousManifest = previous.package.packageJson.zhin;
+    const nextManifest = next.package.packageJson.zhin;
+    return (previous.parent !== next.parent
+        || previous.instanceKey !== next.instanceKey
+        || previous.package.root !== next.package.root
+        || previous.package.name !== next.package.name
+        || previousManifest.entry !== nextManifest.entry
+        || previousManifest.runtime !== nextManifest.runtime
+        || previousManifest.engine !== nextManifest.engine);
+}
+function childOrderChanged(previous, next) {
+    for (const [id, node] of next) {
+        const old = previous.get(id);
+        if (!old)
+            continue;
+        const oldChildren = old.children.map((child) => child.id);
+        const nextChildren = node.children.map((child) => child.id);
+        if (!sameValues(oldChildren, nextChildren))
+            return true;
+    }
+    return false;
+}
+function changedFeaturePackages(previous, next) {
+    const previousPackages = featurePackages(previous);
+    const result = new Set();
+    for (const [root, pkg] of featurePackages(next)) {
+        const old = previousPackages.get(root);
+        if (!old)
+            continue;
+        const oldManifest = old.packageJson.zhin;
+        const nextManifest = pkg.packageJson.zhin;
+        if (old.name !== pkg.name
+            || oldManifest.entry !== nextManifest.entry
+            || oldManifest.engine !== nextManifest.engine
+            || oldManifest.featureApi !== nextManifest.featureApi)
+            result.add(root);
+    }
+    return result;
+}
+function featurePackages(graph) {
+    const packages = new Map();
+    for (const node of indexGraph(graph).values()) {
+        for (const feature of node.features) {
+            packages.set(resolve(feature.package.root), feature.package);
+        }
+    }
+    return packages;
+}
+function difference(left, right) {
+    const rightKeys = new Set(right.map(featureMountKey));
+    return Object.freeze(left.filter((mount) => !rightKeys.has(featureMountKey(mount))));
+}
+function featureMountKey(mount) {
+    return `${mount.owner}\0${mount.packageRoot}`;
+}
+function sameValues(left, right) {
+    return left.length === right.length && left.every((value, index) => value === right[index]);
+}

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

@@ -0,0 +1,23 @@
+/**
+ * ESM resolve hook: when a relative/absolute `.js` specifier fails and a
+ * sibling `.ts` / `.tsx` exists, rewrite to that source file.
+ *
+ * Needed for Plugin Runtime on Node 22.6–22.17 with `--experimental-strip-types`:
+ * TypeScript authoring uses `.js` import suffixes, but strip-types does not
+ * remap missing `.js` → `.ts` the way `tsc`/tsx do.
+ */
+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;
+}>;
+/** Register once for the current process (safe to call from CLI / RootHost). */
+export declare function ensureTypeScriptSpecifierRemap(): void;