@zhin.js/runtime 1.0.0

package/lib/package-resolver.d.ts

@@ -0,0 +1,23 @@
+import { type PackageJson } from './manifest.js';
+export interface ResolvedPackage {
+    readonly name: string;
+    readonly root: string;
+    readonly packageJson: PackageJson;
+    readonly source: 'workspace' | 'node_modules';
+}
+export interface PackageResolver {
+    root(root: string): Promise<ResolvedPackage>;
+    resolve(request: string, from: ResolvedPackage): Promise<ResolvedPackage>;
+    workspacePackages(): readonly ResolvedPackage[];
+}
+export declare class PackageResolutionError extends Error {
+    readonly request?: string | undefined;
+    constructor(message: string, request?: string | undefined);
+}
+export declare class NodePackageResolver implements PackageResolver {
+    #private;
+    static create(projectRoot: string): Promise<NodePackageResolver>;
+    root(root: string): Promise<ResolvedPackage>;
+    workspacePackages(): readonly ResolvedPackage[];
+    resolve(request: string, from: ResolvedPackage): Promise<ResolvedPackage>;
+}

package/lib/package-resolver.js

@@ -0,0 +1,121 @@
+import { access, readFile, readdir, realpath } from 'node:fs/promises';
+import { dirname, join, resolve } from 'node:path';
+import { parsePackageJson } from './manifest.js';
+export class PackageResolutionError extends Error {
+    request;
+    constructor(message, request) {
+        super(message);
+        this.request = request;
+        this.name = 'PackageResolutionError';
+    }
+}
+export class NodePackageResolver {
+    #workspaceByName = new Map();
+    #cache = new Map();
+    static async create(projectRoot) {
+        const resolver = new NodePackageResolver();
+        const root = await resolver.#readPackage(projectRoot, 'workspace');
+        resolver.#workspaceByName.set(root.name, root);
+        for (const directory of ['packages', 'plugins']) {
+            const parent = join(projectRoot, directory);
+            for (const entry of await safeReadDirectories(parent)) {
+                const packageRoot = join(parent, entry);
+                if (await exists(join(packageRoot, 'pnpm-workspace.yaml'))) {
+                    throw new PackageResolutionError(`Nested workspace is not allowed: ${packageRoot}`);
+                }
+                if (directory === 'plugins' && await exists(join(packageRoot, 'plugins'))) {
+                    throw new PackageResolutionError(`Nested local Plugin directory is not allowed: ${join(packageRoot, 'plugins')}`);
+                }
+                if (!await exists(join(packageRoot, 'package.json')))
+                    continue;
+                const pkg = await resolver.#readPackage(packageRoot, 'workspace');
+                if (resolver.#workspaceByName.has(pkg.name)) {
+                    throw new PackageResolutionError(`Duplicate workspace package: ${pkg.name}`);
+                }
+                resolver.#workspaceByName.set(pkg.name, pkg);
+            }
+        }
+        return resolver;
+    }
+    async root(root) {
+        return this.#readPackage(root, 'workspace');
+    }
+    workspacePackages() {
+        return [...this.#workspaceByName.values()];
+    }
+    async resolve(request, from) {
+        const specification = declaredDependency(request, from.packageJson);
+        const workspace = this.#workspaceByName.get(request);
+        if (specification.startsWith('workspace:')) {
+            if (workspace)
+                return workspace;
+            // Examples live outside the monorepo packages/plugins scan roots; pnpm still
+            // links workspace:* into node_modules, so fall through before failing.
+        }
+        else if (workspace) {
+            return workspace;
+        }
+        let current = from.root;
+        while (true) {
+            const packageRoot = join(current, 'node_modules', ...request.split('/'));
+            if (await exists(join(packageRoot, 'package.json'))) {
+                return this.#readPackage(packageRoot, 'node_modules');
+            }
+            const parent = dirname(current);
+            if (parent === current)
+                break;
+            current = parent;
+        }
+        throw new PackageResolutionError(specification.startsWith('workspace:')
+            ? `Workspace dependency ${request} declared by ${from.name} is missing`
+            : `Cannot resolve ${request} from ${from.name}`, request);
+    }
+    async #readPackage(packageRoot, source) {
+        const normalized = await realpath(resolve(packageRoot));
+        const cached = this.#cache.get(normalized);
+        if (cached)
+            return cached;
+        const file = join(normalized, 'package.json');
+        const content = await readFile(file, 'utf8');
+        const packageJson = parsePackageJson(JSON.parse(content), file);
+        const result = Object.freeze({
+            name: packageJson.name,
+            root: normalized,
+            packageJson,
+            source,
+        });
+        this.#cache.set(normalized, result);
+        return result;
+    }
+}
+function declaredDependency(request, pkg) {
+    const specification = (pkg.dependencies?.[request]
+        ?? pkg.optionalDependencies?.[request]);
+    if (!specification) {
+        throw new PackageResolutionError(`${pkg.name} references ${request} in zhin manifest but does not declare it as a package dependency`, request);
+    }
+    return specification;
+}
+async function safeReadDirectories(parent) {
+    try {
+        const entries = await readdir(parent, { withFileTypes: true });
+        return entries.filter((entry) => entry.isDirectory()).map((entry) => entry.name);
+    }
+    catch (error) {
+        if (isNotFound(error))
+            return [];
+        throw error;
+    }
+}
+async function exists(path) {
+    try {
+        await access(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function isNotFound(error) {
+    return error instanceof Error && 'code' in error && error.code === 'ENOENT';
+}

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

@@ -0,0 +1,38 @@
+import { DisposeStack, Scope, type Dispose, type GenerationHandoff, type GenerationHandoffRegistry, type PluginId, type PluginNodeSnapshot, 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';
+import type { PluginGraphNode } from './project-graph.js';
+import type { IsolatedPluginRuntimePort } from './isolation.js';
+export type PluginConfigResolver = (node: PluginGraphNode) => unknown;
+export interface RootResourceContext {
+    readonly resources: Scope;
+    readonly lifecycle: DisposeStack;
+    readonly handoff: GenerationHandoffRegistry;
+}
+export type RootResourceInstaller = (context: RootResourceContext) => void | Promise<void>;
+export interface PluginAssemblySeed {
+    readonly scopes: ReadonlyMap<PluginId, Scope>;
+    readonly tree: ReadonlyMap<PluginId, PluginNodeSnapshot>;
+    readonly config: ReadonlyMap<PluginId, unknown>;
+    readonly resources: ReadonlyMap<PluginId, ReadonlyMap<TokenId, unknown>>;
+}
+/** Assembles Plugin setup into mutable shadow maps without publishing them. */
+export declare class PluginScopeAssembler {
+    #private;
+    private readonly modules;
+    private readonly configResolver;
+    private readonly environment;
+    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);
+    removeSubtrees(roots: readonly PluginId[]): void;
+    setupTree(node: PluginGraphNode): Promise<void>;
+    synchronizeTree(node: PluginGraphNode): void;
+    createdScopeDisposers(): readonly (readonly [PluginId, Dispose])[];
+    generationHandoff(): GenerationHandoff | undefined;
+}

package/lib/plugin-scope-assembler.js

@@ -0,0 +1,167 @@
+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';
+/** Assembles Plugin setup into mutable shadow maps without publishing them. */
+export class PluginScopeAssembler {
+    modules;
+    configResolver;
+    environment;
+    installResources;
+    isolation;
+    scopes;
+    tree;
+    config;
+    resources;
+    #created = [];
+    #handoffs = new GenerationHandoffStack();
+    #envStores;
+    constructor(modules, configResolver, environment, installResources, environmentLayers = {}, seed, isolation) {
+        this.modules = modules;
+        this.configResolver = configResolver;
+        this.environment = environment;
+        this.installResources = installResources;
+        this.isolation = isolation;
+        this.#envStores = new EnvStoreFactory(environment, environmentLayers);
+        this.scopes = new Map(seed?.scopes);
+        this.tree = new Map(seed?.tree);
+        this.config = new Map(seed?.config);
+        this.resources = new Map(seed?.resources);
+    }
+    removeSubtrees(roots) {
+        // Seeded Scopes belong to a committed generation. Removing a map entry
+        // only prepares the shadow view; GenerationAssets owns eventual disposal.
+        for (const owner of [...this.scopes.keys()]) {
+            if (!roots.some((root) => isWithin(owner, root)))
+                continue;
+            this.scopes.delete(owner);
+            this.tree.delete(owner);
+            this.config.delete(owner);
+            this.resources.delete(owner);
+        }
+    }
+    async setupTree(node) {
+        const manifest = node.package.packageJson.zhin;
+        const parentScope = node.parent ? this.scopes.get(node.parent) : undefined;
+        if (node.parent && !parentScope)
+            throw new Error(`Missing parent scope for ${node.id}`);
+        const scope = new Scope(node.id, parentScope);
+        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));
+        if (!node.parent) {
+            scope.provide(runtimeEnvironmentToken, this.environment);
+            await this.installResources?.({
+                resources: scope,
+                lifecycle: scope.disposers,
+                handoff: this.#handoffs,
+            });
+        }
+        const config = Object.freeze(this.configResolver(node) ?? {});
+        const view = { get: () => config };
+        const plugin = Object.freeze({
+            id: node.id,
+            instanceKey: node.instanceKey,
+            parent: node.parent,
+            root: rootPluginId(),
+            role: node.parent ? 'child' : 'root',
+        });
+        let metadata;
+        if (manifest.runtime === 'isolated') {
+            if (!node.parent)
+                throw new Error('Root Plugin cannot use runtime: isolated');
+            if (node.features.length > 0) {
+                throw new Error(`Isolated Plugin ${node.id} cannot mount Host Feature providers`);
+            }
+            if (!this.isolation) {
+                throw new Error(`Isolated Plugin runtime adapter is required: ${node.package.name}`);
+            }
+            const prepared = await this.isolation.prepare({
+                owner: node.id,
+                parent: node.parent,
+                packageName: node.package.name,
+                entry: resolve(node.package.root, manifest.entry),
+                config,
+                environment: this.environment,
+            });
+            // Ownership transfers to the shadow Scope immediately. Every later
+            // validation or binding failure is then covered by normal rollback.
+            scope.disposers.add(prepared.dispose);
+            if (!prepared.descriptor.name) {
+                throw new TypeError(`Isolated Plugin ${node.package.name} returned an invalid descriptor`);
+            }
+            for (const binding of prepared.resources ?? []) {
+                scope.provide(binding.token, binding.value);
+            }
+            if (prepared.handoff)
+                this.#handoffs.add(prepared.handoff);
+            metadata = prepared.descriptor.metadata;
+        }
+        else {
+            const module = await this.modules.load(resolve(node.package.root, manifest.entry));
+            const definition = module.default;
+            if (!definition || typeof definition.name !== 'string') {
+                throw new TypeError(`${node.package.name} does not default-export a Plugin definition`);
+            }
+            for (const token of definition.requires ?? []) {
+                if (!scope.has(token)) {
+                    throw new Error(`Missing resource ${token.id} for Plugin ${node.id}`);
+                }
+            }
+            const returned = await definition.setup?.({
+                plugin,
+                config: view,
+                resources: scope,
+                lifecycle: scope.disposers,
+                handoff: this.#handoffs,
+            });
+            if (returned)
+                scope.disposers.add(returned);
+            metadata = definition.metadata;
+        }
+        scope.seal();
+        this.tree.set(node.id, Object.freeze({
+            id: node.id,
+            instanceKey: node.instanceKey,
+            packageName: node.package.name,
+            packageRoot: node.package.root,
+            parent: node.parent,
+            children: Object.freeze(node.children.map((child) => child.id)),
+            metadata,
+        }));
+        this.config.set(node.id, config);
+        this.resources.set(node.id, scope.snapshot());
+        for (const child of node.children)
+            await this.setupTree(child);
+    }
+    synchronizeTree(node) {
+        const current = this.tree.get(node.id);
+        if (!current)
+            throw new Error(`Missing Plugin tree node: ${node.id}`);
+        this.tree.set(node.id, Object.freeze({
+            ...current,
+            instanceKey: node.instanceKey,
+            packageName: node.package.name,
+            packageRoot: node.package.root,
+            parent: node.parent,
+            children: Object.freeze(node.children.map((child) => child.id)),
+        }));
+        for (const child of node.children)
+            this.synchronizeTree(child);
+    }
+    createdScopeDisposers() {
+        return this.#created.map((owner) => {
+            const scope = this.scopes.get(owner);
+            if (!scope)
+                throw new Error(`Missing created Scope: ${owner}`);
+            return [owner, () => scope.disposers.dispose()];
+        });
+    }
+    generationHandoff() {
+        return this.#handoffs.seal();
+    }
+}
+function isWithin(plugin, root) {
+    return plugin === root || plugin.startsWith(`${root}/`);
+}

package/lib/process-restart.d.ts

@@ -0,0 +1,15 @@
+import type { ProcessInvalidationPlan } from './invalidation-planner.js';
+export interface ProcessRestartAdapter {
+    restart(plan: ProcessInvalidationPlan): void | Promise<void>;
+}
+export interface StoppableRoot {
+    stop(): Promise<void>;
+}
+/** Drains one Root lifecycle before handing process replacement to the Host. */
+export declare class RootProcessRestartExecutor {
+    #private;
+    private readonly root;
+    private readonly adapter;
+    constructor(root: StoppableRoot, adapter: ProcessRestartAdapter);
+    execute(plan: ProcessInvalidationPlan): Promise<void>;
+}

package/lib/process-restart.js

@@ -0,0 +1,29 @@
+/** Drains one Root lifecycle before handing process replacement to the Host. */
+export class RootProcessRestartExecutor {
+    root;
+    adapter;
+    #execution;
+    constructor(root, adapter) {
+        this.root = root;
+        this.adapter = adapter;
+    }
+    execute(plan) {
+        if (!this.#execution) {
+            const request = clonePlan(plan);
+            // Keep the completed promise: one process incarnation may request its
+            // replacement exactly once, even if several watcher paths converge.
+            this.#execution = Promise.resolve().then(async () => {
+                await this.root.stop();
+                await this.adapter.restart(request);
+            });
+        }
+        return this.#execution;
+    }
+}
+function clonePlan(plan) {
+    return Object.freeze({
+        kind: 'process',
+        changed: Object.freeze([...plan.changed]),
+        reasons: Object.freeze([...plan.reasons]),
+    });
+}

package/lib/project-graph.d.ts

@@ -0,0 +1,30 @@
+import { type PluginId } from '@zhin.js/plugin-runtime';
+import type { PackageReference } from './manifest.js';
+import { type PackageResolver, type ResolvedPackage } from './package-resolver.js';
+export interface FeatureRequirementNode {
+    readonly reference: PackageReference;
+    readonly package: ResolvedPackage;
+}
+export interface PluginGraphNode {
+    readonly id: PluginId;
+    readonly instanceKey: string;
+    readonly package: ResolvedPackage;
+    readonly parent?: PluginId;
+    readonly features: readonly FeatureRequirementNode[];
+    readonly children: readonly PluginGraphNode[];
+}
+export interface ProjectGraph {
+    readonly root: PluginGraphNode;
+    readonly packages: ReadonlyMap<string, ResolvedPackage>;
+    readonly buildOrder: readonly ResolvedPackage[];
+}
+export declare class ProjectGraphError extends Error {
+    constructor(message: string);
+}
+export declare class ProjectGraphService {
+    #private;
+    private readonly resolver;
+    private readonly engineVersion;
+    constructor(resolver: PackageResolver, engineVersion?: string);
+    inspect(projectRoot: string): Promise<ProjectGraph>;
+}

package/lib/project-graph.js

@@ -0,0 +1,129 @@
+import { childPluginId, rootPluginId } from '@zhin.js/plugin-runtime';
+import { assertFeatureApi, assertPackageEngine, runtimeEngineVersion, } from './compatibility.js';
+import { PackageResolutionError, } from './package-resolver.js';
+export class ProjectGraphError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'ProjectGraphError';
+    }
+}
+export class ProjectGraphService {
+    resolver;
+    engineVersion;
+    constructor(resolver, engineVersion = runtimeEngineVersion) {
+        this.resolver = resolver;
+        this.engineVersion = engineVersion;
+    }
+    async inspect(projectRoot) {
+        const rootPackage = await this.resolver.root(projectRoot);
+        assertPackageType(rootPackage, 'plugin');
+        const packages = new Map();
+        const root = await this.#visitPlugin(rootPackage, rootPluginId(), 'root', undefined, [], packages);
+        for (const pkg of this.resolver.workspacePackages())
+            addPackage(packages, pkg);
+        return Object.freeze({
+            root,
+            packages,
+            buildOrder: topologicalBuildOrder(packages),
+        });
+    }
+    async #visitPlugin(pkg, id, instanceKey, parent, ancestors, packages) {
+        if (ancestors.includes(pkg.root)) {
+            throw new ProjectGraphError(`Plugin cycle detected: ${[...ancestors, pkg.root].join(' -> ')}`);
+        }
+        const manifest = assertPackageType(pkg, 'plugin');
+        assertPackageEngine(pkg, this.engineVersion);
+        addPackage(packages, pkg);
+        const featurePackages = new Set();
+        const features = await Promise.all(manifest.features.map(async (reference) => {
+            if (featurePackages.has(reference.package)) {
+                throw new ProjectGraphError(`Duplicate Feature requirement ${reference.package} in ${pkg.name}`);
+            }
+            featurePackages.add(reference.package);
+            const resolved = await resolveReference(this.resolver, pkg, reference);
+            if (!resolved)
+                return undefined;
+            assertPackageType(resolved, 'feature');
+            assertPackageEngine(resolved, this.engineVersion);
+            assertFeatureApi(pkg, reference, resolved);
+            addPackage(packages, resolved);
+            return Object.freeze({ reference, package: resolved });
+        }));
+        const instanceKeys = new Set();
+        const children = await Promise.all(manifest.plugins.map(async (reference) => {
+            if (instanceKeys.has(reference.instanceKey)) {
+                throw new ProjectGraphError(`Duplicate child instanceKey ${reference.instanceKey} in ${pkg.name}`);
+            }
+            instanceKeys.add(reference.instanceKey);
+            const resolved = await resolveReference(this.resolver, pkg, reference);
+            if (!resolved)
+                return undefined;
+            assertPackageType(resolved, 'plugin');
+            return this.#visitPlugin(resolved, childPluginId(id, reference.instanceKey), reference.instanceKey, id, [...ancestors, pkg.root], packages);
+        }));
+        return Object.freeze({
+            id,
+            instanceKey,
+            package: pkg,
+            parent,
+            features: Object.freeze(features.filter(isDefined)),
+            children: Object.freeze(children.filter(isDefined)),
+        });
+    }
+}
+async function resolveReference(resolver, from, reference) {
+    try {
+        return await resolver.resolve(reference.package, from);
+    }
+    catch (error) {
+        if (reference.optional
+            && error instanceof PackageResolutionError
+            && error.message.startsWith('Cannot resolve'))
+            return undefined;
+        throw error;
+    }
+}
+function assertPackageType(pkg, type) {
+    if (pkg.packageJson.zhin.type !== type) {
+        throw new ProjectGraphError(`${pkg.name} must be a Zhin ${type} package`);
+    }
+    return pkg.packageJson.zhin;
+}
+function topologicalBuildOrder(packages) {
+    const result = [];
+    const visited = new Set();
+    const visiting = new Set();
+    const visitPackage = (pkg) => {
+        if (visited.has(pkg.root))
+            return;
+        if (visiting.has(pkg.root)) {
+            throw new ProjectGraphError(`Package dependency cycle detected at ${pkg.name}`);
+        }
+        visiting.add(pkg.root);
+        const dependencies = {
+            ...pkg.packageJson.dependencies,
+            ...pkg.packageJson.optionalDependencies,
+        };
+        for (const name of Object.keys(dependencies)) {
+            const dependency = packages.get(name);
+            if (dependency)
+                visitPackage(dependency);
+        }
+        visiting.delete(pkg.root);
+        visited.add(pkg.root);
+        result.push(pkg);
+    };
+    for (const pkg of packages.values())
+        visitPackage(pkg);
+    return Object.freeze(result);
+}
+function isDefined(value) {
+    return value !== undefined;
+}
+function addPackage(packages, pkg) {
+    const previous = packages.get(pkg.name);
+    if (previous && previous.root !== pkg.root) {
+        throw new ProjectGraphError(`Multiple package locations for ${pkg.name} are not supported in one generation`);
+    }
+    packages.set(pkg.name, pkg);
+}

package/lib/restart-boundary.d.ts

@@ -0,0 +1,6 @@
+import type { ProcessInvalidationPlan } from './invalidation-planner.js';
+import type { ProjectGraph } from './project-graph.js';
+/** Decides which manifest changes cannot remain inside a generation transaction. */
+export declare class RestartBoundaryPlanner {
+    plan(previous: ProjectGraph, next: ProjectGraph, changed: readonly string[]): ProcessInvalidationPlan | undefined;
+}

package/lib/restart-boundary.js

@@ -0,0 +1,68 @@
+import { resolve } from 'node:path';
+import { isDeepStrictEqual } from 'node:util';
+import { graphNodes } from './topology-transaction.js';
+/** Decides which manifest changes cannot remain inside a generation transaction. */
+export class RestartBoundaryPlanner {
+    plan(previous, next, changed) {
+        const reasons = new Set();
+        const previousPackages = mountedPackages(previous);
+        const nextPackages = mountedPackages(next);
+        for (const [root, pkg] of nextPackages) {
+            const old = previousPackages.get(root);
+            if (!old)
+                continue;
+            if (runtimeAbiChanged(old, pkg)) {
+                reasons.add(`package runtime ABI changed: ${pkg.name}`);
+            }
+            const oldManifest = old.packageJson.zhin;
+            const nextManifest = pkg.packageJson.zhin;
+            if (oldManifest.engine !== nextManifest.engine) {
+                reasons.add(`runtime engine contract changed: ${pkg.name}`);
+            }
+            if (oldManifest.type === 'feature'
+                && nextManifest.type === 'feature'
+                && oldManifest.featureApi !== nextManifest.featureApi)
+                reasons.add(`Feature API contract changed: ${pkg.name}`);
+            if (oldManifest.type === 'plugin'
+                && nextManifest.type === 'plugin'
+                && oldManifest.runtime !== nextManifest.runtime)
+                reasons.add(`Plugin execution runtime changed: ${pkg.name}`);
+        }
+        const oldRoot = previous.root.package;
+        const nextRoot = next.root.package;
+        const oldRootManifest = oldRoot.packageJson.zhin;
+        const nextRootManifest = nextRoot.packageJson.zhin;
+        if (oldRoot.name !== nextRoot.name
+            || oldRoot.root !== nextRoot.root
+            || oldRootManifest.entry !== nextRootManifest.entry)
+            reasons.add('Root Plugin runtime contract changed');
+        if (reasons.size === 0)
+            return undefined;
+        return Object.freeze({
+            kind: 'process',
+            changed: Object.freeze([...changed].map((source) => resolve(source))),
+            reasons: Object.freeze([...reasons]),
+        });
+    }
+}
+function mountedPackages(graph) {
+    const packages = new Map();
+    for (const node of graphNodes(graph).values()) {
+        packages.set(resolve(node.package.root), node.package);
+        for (const feature of node.features) {
+            packages.set(resolve(feature.package.root), feature.package);
+        }
+    }
+    return packages;
+}
+function runtimeAbiChanged(previous, next) {
+    return !isDeepStrictEqual(runtimeAbi(previous), runtimeAbi(next));
+}
+function runtimeAbi(pkg) {
+    return {
+        type: pkg.packageJson.type,
+        main: pkg.packageJson.main,
+        exports: pkg.packageJson.exports,
+        imports: pkg.packageJson.imports,
+    };
+}

package/lib/root-runtime.d.ts

@@ -0,0 +1,37 @@
+import { RootController, type ControlErrorHandler, type PluginId, type RuntimeSnapshot } from '@zhin.js/plugin-runtime';
+import { type RuntimeConfigDocument } from './config-composer.js';
+import { type ConfigDocumentPort } from './config-document.js';
+import { type ConfigPatch } from './config-patch-planner.js';
+import { type 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 { HmrCoordinator, type HmrCoordinatorOptions } from './hmr-coordinator.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';
+export interface RootRuntimeOptions {
+    readonly projectRoot: string;
+    readonly modules: ModuleRuntime;
+    readonly environment: RuntimeEnvironment;
+    readonly environmentVariables?: EnvironmentLayers;
+    readonly config?: PluginConfigResolver | RuntimeConfigDocument | ConfigDocumentPort;
+    readonly installResources?: RootResourceInstaller;
+    readonly isolation?: IsolatedPluginRuntimePort;
+    readonly onControlError?: ControlErrorHandler;
+}
+export type RootHmrOptions = Omit<HmrCoordinatorOptions, 'modules' | 'ownership' | 'runtime'>;
+export declare class RootRuntime {
+    #private;
+    readonly controller: RootController;
+    constructor(options: RootRuntimeOptions);
+    get snapshot(): RuntimeSnapshot;
+    get sourceOwnership(): SourceOwnershipIndex;
+    start(): Promise<RuntimeSnapshot>;
+    reload(target?: PluginId | string): Promise<RuntimeSnapshot>;
+    patchConfig(patches: readonly ConfigPatch[]): Promise<RuntimeSnapshot>;
+    createHmrCoordinator(options: RootHmrOptions): HmrCoordinator;
+    createProcessRestartExecutor(adapter: ProcessRestartAdapter): RootProcessRestartExecutor;
+    stop(): Promise<void>;
+}