@zhin.js/runtime 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 凉菜
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,39 @@
+# @zhin.js/runtime
+
+Zhin.js Plugin 树的 Root 生命周期权威。它从静态 package manifest 构建 Plugin instance
+tree，按 owner 组合 schema/config/env，通过 Feature provider 发现 capability，并用
+immutable snapshot、CAS generation 与 lease 驱动局部 HMR。
+
+```ts
+import { EsmModuleRuntime, RootRuntime } from '@zhin.js/runtime';
+
+const runtime = new RootRuntime({
+  projectRoot: process.cwd(),
+  modules: new EsmModuleRuntime(),
+  environment: { mode: 'development' },
+});
+
+await runtime.start();
+```
+
+## 事务边界
+
+- capability 文件变化只 prepare 对应 Slot。
+- child/schema 变化替换最浅受影响 subtree。
+- manifest topology transaction 支持 child/Feature 新增、删除和移动。
+- Root/package ABI、lockfile 和未知 importer 变化升级为 process restart。
+- 候选校验或 handoff 失败不提交 generation；旧 snapshot 保持可用。
+- 最后一个旧 lease 释放后，旧资源才按 children-first 顺序回收。
+
+Runtime 不静态导入 Command、Agent、Page 或 Adapter provider。具体能力由插件 manifest
+动态装配。Ajv 用于整树 schema 校验，semver 用于 engine/Feature API admission；它们只
+属于显式安装的 Root 控制面，不进入 `zhin.js` 默认 IM 安装。
+
+`zhin.js/runtime` 是指向本包的 optional-peer facade。新项目应显式安装本包；这保证
+`zhin.js` 默认 IM 闭包继续满足 10MB 门禁。
+
+```bash
+pnpm --filter @zhin.js/runtime build
+pnpm --filter @zhin.js/runtime test
+pnpm --filter @zhin.js/runtime check:size
+```

package/lib/compatibility.d.ts

@@ -0,0 +1,10 @@
+import type { PackageReference } from './manifest.js';
+import type { ResolvedPackage } from './package-resolver.js';
+export declare const runtimeEngineVersion = "1.0.0";
+export declare class PackageCompatibilityError extends Error {
+    readonly packageName: string;
+    readonly contract: 'engine' | 'feature-api';
+    constructor(packageName: string, contract: 'engine' | 'feature-api', message: string);
+}
+export declare function assertPackageEngine(pkg: ResolvedPackage, engineVersion?: string): void;
+export declare function assertFeatureApi(owner: ResolvedPackage, reference: PackageReference, feature: ResolvedPackage): void;

package/lib/compatibility.js

@@ -0,0 +1,45 @@
+import { createRequire } from 'node:module';
+const require = createRequire(import.meta.url);
+const semver = require('semver');
+export const runtimeEngineVersion = '1.0.0';
+export class PackageCompatibilityError extends Error {
+    packageName;
+    contract;
+    constructor(packageName, contract, message) {
+        super(`Incompatible ${contract} for ${packageName}: ${message}`);
+        this.packageName = packageName;
+        this.contract = contract;
+        this.name = 'PackageCompatibilityError';
+    }
+}
+export function assertPackageEngine(pkg, engineVersion = runtimeEngineVersion) {
+    const range = pkg.packageJson.zhin.engine;
+    if (!range)
+        return;
+    assertRange(pkg.name, 'engine', range);
+    if (!semver.satisfies(engineVersion, range, { includePrerelease: true })) {
+        throw new PackageCompatibilityError(pkg.name, 'engine', `requires ${range}, Runtime provides ${engineVersion}`);
+    }
+}
+export function assertFeatureApi(owner, reference, feature) {
+    const actual = feature.packageJson.zhin.type === 'feature'
+        ? feature.packageJson.zhin.featureApi
+        : undefined;
+    if (actual && !semver.valid(actual)) {
+        throw new PackageCompatibilityError(feature.name, 'feature-api', `declares invalid featureApi version ${actual}`);
+    }
+    if (!reference.api)
+        return;
+    assertRange(owner.name, 'feature-api', reference.api);
+    if (!actual) {
+        throw new PackageCompatibilityError(feature.name, 'feature-api', `must declare a valid featureApi version for ${owner.name}'s ${reference.api} requirement`);
+    }
+    if (!semver.satisfies(actual, reference.api, { includePrerelease: true })) {
+        throw new PackageCompatibilityError(feature.name, 'feature-api', `${owner.name} requires ${reference.api}, provider declares ${actual}`);
+    }
+}
+function assertRange(packageName, contract, range) {
+    if (!semver.validRange(range)) {
+        throw new PackageCompatibilityError(packageName, contract, `invalid semver range ${range}`);
+    }
+}

package/lib/config-composer.d.ts

@@ -0,0 +1,27 @@
+import type { PluginId } from '@zhin.js/plugin-runtime';
+import type { ProjectGraph } from './project-graph.js';
+export type JsonSchema = Readonly<Record<string, unknown>>;
+export type RuntimeConfigDocument = Readonly<Record<string, unknown>>;
+export interface ComposedConfig {
+    readonly effectiveSchema: JsonSchema;
+    readonly document: RuntimeConfigDocument;
+    readonly views: ReadonlyMap<PluginId, unknown>;
+}
+export declare class ConfigSchemaCollisionError extends Error {
+    readonly plugin: PluginId;
+    readonly instanceKey: string;
+    constructor(plugin: PluginId, instanceKey: string);
+}
+export declare class ConfigValidationError extends Error {
+    readonly issues: readonly string[];
+    /** Source config file name, when known (e.g. `zhin.config.yml`). */
+    readonly source?: string | undefined;
+    constructor(issues: readonly string[], 
+    /** Source config file name, when known (e.g. `zhin.config.yml`). */
+    source?: string | undefined);
+}
+export declare class ConfigComposer {
+    compose(graph: ProjectGraph, input?: RuntimeConfigDocument, 
+    /** Source config file name, annotated on ConfigValidationError. */
+    source?: string): Promise<ComposedConfig>;
+}

package/lib/config-composer.js

@@ -0,0 +1,212 @@
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import Ajv2020 from 'ajv/dist/2020.js';
+export class ConfigSchemaCollisionError extends Error {
+    plugin;
+    instanceKey;
+    constructor(plugin, instanceKey) {
+        super(`Config property ${instanceKey} in ${plugin} collides with a child Plugin`);
+        this.plugin = plugin;
+        this.instanceKey = instanceKey;
+        this.name = 'ConfigSchemaCollisionError';
+    }
+}
+export class ConfigValidationError extends Error {
+    issues;
+    source;
+    constructor(issues, 
+    /** Source config file name, when known (e.g. `zhin.config.yml`). */
+    source) {
+        super(`Invalid Plugin config${source ? ` in ${source}` : ''}:\n${issues.map((issue) => `- ${issue}`).join('\n')}`);
+        this.issues = issues;
+        this.source = source;
+        this.name = 'ConfigValidationError';
+    }
+}
+export class ConfigComposer {
+    async compose(graph, input = {}, 
+    /** Source config file name, annotated on ConfigValidationError. */
+    source) {
+        // Effective schemas include child namespaces for whole-tree validation;
+        // ownSchemas retain each package's private configuration contract.
+        const ownSchemas = new Map();
+        const rootOwn = await readOwnSchema(graph.root);
+        ownSchemas.set(graph.root.id, rootOwn);
+        const childSchemas = await Promise.all(graph.root.children.map(async (child) => [
+            child.instanceKey,
+            await composeNode(child, ownSchemas),
+        ]));
+        // Host-level keys (`http`, `database`, `ai`, `mcp`, `a2a`, `speech`,
+        // `htmlRenderer`, `assistant`, `collaboration`, `log_level`) are consumed by CLI Root installers /
+        // start-command, not Plugin ConfigViews.
+        const effectiveSchema = Object.freeze({
+            type: 'object',
+            additionalProperties: false,
+            properties: {
+                plugin: withDefault(rootOwn),
+                plugins: {
+                    type: 'object',
+                    additionalProperties: false,
+                    default: {},
+                    properties: Object.fromEntries(childSchemas.map(([key, schema]) => [key, withDefault(schema)])),
+                },
+                http: Object.freeze({
+                    type: 'object',
+                    additionalProperties: true,
+                }),
+                database: Object.freeze({
+                    type: 'object',
+                    additionalProperties: true,
+                }),
+                ai: Object.freeze({
+                    type: 'object',
+                    additionalProperties: true,
+                }),
+                mcp: Object.freeze({
+                    type: 'object',
+                    additionalProperties: true,
+                }),
+                a2a: Object.freeze({
+                    type: 'object',
+                    additionalProperties: true,
+                }),
+                speech: Object.freeze({
+                    type: 'object',
+                    additionalProperties: true,
+                }),
+                htmlRenderer: Object.freeze({
+                    type: 'object',
+                    additionalProperties: true,
+                }),
+                assistant: Object.freeze({
+                    type: 'object',
+                    additionalProperties: true,
+                }),
+                collaboration: Object.freeze({
+                    type: 'object',
+                    additionalProperties: true,
+                }),
+                log_level: Object.freeze({
+                    type: ['string', 'number'],
+                }),
+            },
+        });
+        const document = structuredClone(input);
+        const validate = new Ajv2020({
+            allErrors: true,
+            useDefaults: true,
+            strict: true,
+            // 当前内置 schema 无需 union（log_level 的 ['string','number'] 是 type 数组，
+            // 不触发 allowUnionTypes）；保留此项是面向未来插件 schema 可能出现的
+            // anyOf/oneOf 标量 union，避免届时 Ajv strict 模式直接报错。
+            allowUnionTypes: true,
+        }).compile(effectiveSchema);
+        if (!validate(document)) {
+            throw new ConfigValidationError(formatErrors(validate.errors ?? []), source);
+        }
+        const views = new Map();
+        // A Plugin never receives its effective node object because that object
+        // also contains descendants. Re-pick fields from the owner's own schema.
+        views.set(graph.root.id, pickOwnFields(document.plugin, requireOwnSchema(ownSchemas, graph.root.id)));
+        collectChildViews(graph.root, document.plugins, ownSchemas, views);
+        return Object.freeze({
+            effectiveSchema,
+            document: Object.freeze(document),
+            views,
+        });
+    }
+}
+async function composeNode(node, ownSchemas) {
+    const own = await readOwnSchema(node);
+    ownSchemas.set(node.id, own);
+    const properties = { ...schemaProperties(own) };
+    for (const child of node.children) {
+        if (Object.hasOwn(properties, child.instanceKey)) {
+            throw new ConfigSchemaCollisionError(node.id, child.instanceKey);
+        }
+        properties[child.instanceKey] = withDefault(await composeNode(child, ownSchemas));
+    }
+    return Object.freeze({ ...own, properties });
+}
+async function readOwnSchema(node) {
+    const file = join(node.package.root, 'schema.json');
+    let value;
+    try {
+        value = JSON.parse(await readFile(file, 'utf8'));
+    }
+    catch (error) {
+        if (error instanceof Error && 'code' in error && error.code === 'ENOENT') {
+            value = { type: 'object', additionalProperties: false, properties: {} };
+        }
+        else {
+            throw error;
+        }
+    }
+    if (!value || typeof value !== 'object' || Array.isArray(value)) {
+        throw new TypeError(`${file} must contain a JSON Schema object`);
+    }
+    const { $schema: _schema, $id: _id, ...schema } = value;
+    if (schema.type !== undefined && schema.type !== 'object') {
+        throw new TypeError(`${file} root schema type must be object`);
+    }
+    return Object.freeze({
+        type: 'object',
+        additionalProperties: false,
+        ...schema,
+        properties: schemaProperties(schema),
+    });
+}
+function schemaProperties(schema) {
+    const properties = schema.properties;
+    if (properties === undefined)
+        return {};
+    if (!properties || typeof properties !== 'object' || Array.isArray(properties)) {
+        throw new TypeError('JSON Schema properties must be an object');
+    }
+    return { ...properties };
+}
+function withDefault(schema) {
+    return Object.freeze({ ...schema, default: schema.default ?? {} });
+}
+function collectChildViews(parent, value, ownSchemas, views) {
+    const record = value && typeof value === 'object'
+        ? value
+        : {};
+    for (const child of parent.children) {
+        const childConfig = record[child.instanceKey] ?? Object.freeze({});
+        views.set(child.id, pickOwnFields(childConfig, requireOwnSchema(ownSchemas, child.id)));
+        collectChildViews(child, childConfig, ownSchemas, views);
+    }
+}
+function pickOwnFields(value, schema) {
+    const record = value && typeof value === 'object'
+        ? value
+        : {};
+    const result = {};
+    for (const key of Object.keys(schemaProperties(schema))) {
+        if (Object.hasOwn(record, key))
+            result[key] = record[key];
+    }
+    return Object.freeze(result);
+}
+function requireOwnSchema(schemas, plugin) {
+    const schema = schemas.get(plugin);
+    if (!schema)
+        throw new Error(`Missing own config schema for ${plugin}`);
+    return schema;
+}
+function formatErrors(errors) {
+    return errors.map((error) => {
+        const base = `${error.instancePath || '/'} ${error.message ?? error.keyword}`;
+        // Ajv params pinpoint the offending key / allowed enum so users can find
+        // the typo'd field instead of a bare "must NOT have additional properties".
+        const params = error.params;
+        if (typeof params?.additionalProperty === 'string') {
+            return `${base} (additionalProperty: ${params.additionalProperty})`;
+        }
+        if (Array.isArray(params?.allowedValues)) {
+            return `${base} (allowedValues: ${JSON.stringify(params.allowedValues)})`;
+        }
+        return base;
+    });
+}

package/lib/config-document.d.ts

@@ -0,0 +1,19 @@
+import type { RuntimeConfigDocument } from './config-composer.js';
+import type { ConfigPatch } from './config-patch-planner.js';
+export interface ConfigDocumentSnapshot {
+    readonly document: RuntimeConfigDocument;
+    readonly revision: string;
+}
+/** A prepared write is inert until the generation handoff activates it. */
+export interface PreparedConfigDocument {
+    readonly document: RuntimeConfigDocument;
+    commit(): Promise<ConfigDocumentSnapshot>;
+    rollback(): Promise<void>;
+}
+export interface ConfigDocumentPort {
+    read(): Promise<ConfigDocumentSnapshot>;
+    prepare(current: ConfigDocumentSnapshot, patches: readonly ConfigPatch[]): Promise<PreparedConfigDocument>;
+}
+export declare class ConfigDocumentDivergenceError extends Error {
+    constructor();
+}

package/lib/config-document.js

@@ -0,0 +1,6 @@
+export class ConfigDocumentDivergenceError extends Error {
+    constructor() {
+        super('ConfigDocument adapter candidate differs from the validated Runtime candidate');
+        this.name = 'ConfigDocumentDivergenceError';
+    }
+}

package/lib/config-patch-planner.d.ts

@@ -0,0 +1,25 @@
+import { type PluginId } from '@zhin.js/plugin-runtime';
+import { ConfigComposer, type ComposedConfig, type RuntimeConfigDocument } from './config-composer.js';
+import type { ProjectGraph } from './project-graph.js';
+export type ConfigPatch = {
+    readonly op: 'set';
+    readonly path: readonly string[];
+    readonly value: unknown;
+} | {
+    readonly op: 'remove';
+    readonly path: readonly string[];
+};
+export interface ConfigPatchPlan extends ComposedConfig {
+    readonly candidate: RuntimeConfigDocument;
+    readonly documentChanged: boolean;
+    readonly roots: readonly PluginId[];
+}
+export declare class ConfigPatchPathError extends Error {
+    constructor(message: string);
+}
+/** Validates a candidate document before deriving its minimal replacement forest. */
+export declare class ConfigPatchPlanner {
+    private readonly composer;
+    constructor(composer?: ConfigComposer);
+    plan(graph: ProjectGraph, current: RuntimeConfigDocument, patches: readonly ConfigPatch[]): Promise<ConfigPatchPlan>;
+}

package/lib/config-patch-planner.js

@@ -0,0 +1,126 @@
+import { isDeepStrictEqual } from 'node:util';
+import { rootPluginId } from '@zhin.js/plugin-runtime';
+import { ConfigComposer, } from './config-composer.js';
+export class ConfigPatchPathError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'ConfigPatchPathError';
+    }
+}
+/** Validates a candidate document before deriving its minimal replacement forest. */
+export class ConfigPatchPlanner {
+    composer;
+    constructor(composer = new ConfigComposer()) {
+        this.composer = composer;
+    }
+    async plan(graph, current, patches) {
+        const previous = await this.composer.compose(graph, current);
+        let candidate = structuredClone(current);
+        for (const patch of patches)
+            candidate = applyPatch(candidate, patch);
+        const next = await this.composer.compose(graph, candidate);
+        const changed = indexGraph(graph)
+            .filter((node) => !isDeepStrictEqual(previous.views.get(node.id), next.views.get(node.id)))
+            .map((node) => node.id);
+        return Object.freeze({
+            ...next,
+            candidate: Object.freeze(candidate),
+            documentChanged: !isDeepStrictEqual(current, candidate),
+            roots: Object.freeze(collapseRoots(changed)),
+        });
+    }
+}
+function applyPatch(document, patch) {
+    assertPath(patch.path);
+    if (patch.path.length === 0) {
+        if (patch.op === 'remove') {
+            throw new ConfigPatchPathError('The config document root cannot be removed');
+        }
+        return cloneDocument(patch.value);
+    }
+    if (patch.op === 'set')
+        setValue(document, patch.path, structuredClone(patch.value));
+    else
+        removeValue(document, patch.path);
+    return document;
+}
+function setValue(document, path, value) {
+    let target = document;
+    for (const [index, segment] of path.slice(0, -1).entries()) {
+        const existing = target[segment];
+        if (existing === undefined) {
+            const created = {};
+            target[segment] = created;
+            target = created;
+        }
+        else {
+            target = requireRecord(existing, path.slice(0, index + 1));
+        }
+    }
+    target[lastSegment(path)] = value;
+}
+function removeValue(document, path) {
+    let target = document;
+    for (const [index, segment] of path.slice(0, -1).entries()) {
+        const existing = target[segment];
+        if (existing === undefined)
+            return;
+        target = requireRecord(existing, path.slice(0, index + 1));
+    }
+    delete target[lastSegment(path)];
+}
+function cloneDocument(value) {
+    return requireRecord(structuredClone(value), []);
+}
+function requireRecord(value, path) {
+    if (!value || typeof value !== 'object' || Array.isArray(value)) {
+        throw new ConfigPatchPathError(`Config path ${pointer(path)} is not an object`);
+    }
+    return value;
+}
+function assertPath(path) {
+    for (const segment of path) {
+        if (!segment || segment === '__proto__' || segment === 'prototype' || segment === 'constructor') {
+            throw new ConfigPatchPathError(`Unsafe config path segment: ${segment || '<empty>'}`);
+        }
+    }
+}
+function lastSegment(path) {
+    const segment = path[path.length - 1];
+    if (!segment)
+        throw new ConfigPatchPathError('Config patch path is empty');
+    return segment;
+}
+function pointer(path) {
+    if (path.length === 0)
+        return '/';
+    return `/${path.map((segment) => segment.replaceAll('~', '~0').replaceAll('/', '~1')).join('/')}`;
+}
+function indexGraph(graph) {
+    const result = [];
+    const visit = (node) => {
+        result.push(node);
+        for (const child of node.children)
+            visit(child);
+    };
+    visit(graph.root);
+    return result;
+}
+function collapseRoots(plugins) {
+    if (plugins.includes(rootPluginId()))
+        return [rootPluginId()];
+    const selected = new Set(plugins);
+    return plugins.filter((plugin) => {
+        let parent = parentPlugin(plugin);
+        while (parent) {
+            if (selected.has(parent))
+                return false;
+            parent = parentPlugin(parent);
+        }
+        return true;
+    });
+}
+function parentPlugin(plugin) {
+    const separator = plugin.lastIndexOf('/');
+    return separator < 0 ? undefined : plugin.slice(0, separator);
+}

package/lib/environment-store.d.ts

@@ -0,0 +1,56 @@
+import { type PluginId } from '@zhin.js/plugin-runtime';
+import type { RuntimeEnvironment } from './environment.js';
+export type EnvironmentSource = Readonly<Record<string, string | undefined>>;
+export interface EnvironmentLayers {
+    readonly base?: EnvironmentSource;
+    readonly environments?: Readonly<Record<string, EnvironmentSource>>;
+    readonly plugins?: Readonly<Record<string, EnvironmentSource>>;
+}
+export interface EnvSchema<T> {
+    readonly secretKeys?: readonly string[];
+    parse(source: EnvironmentSource): T;
+}
+export interface EnvStore {
+    readonly owner: PluginId;
+    readonly environment: RuntimeEnvironment;
+    has(key: string): boolean;
+    get(key: string): string | undefined;
+    require(key: string): string;
+    parse<T>(schema: EnvSchema<T>): Readonly<T>;
+    /** Strict expansion: missing keys throw `EnvironmentVariableMissingError`. */
+    expand<T>(value: T): T;
+    /**
+     * Config-document expansion for Root compose.
+     * Missing keys become `""` so adapters that require credentials soft-fail at
+     * create instead of treating literal `${VAR}` as a real token.
+     */
+    expandMissingAsEmpty<T>(value: T): T;
+    redact(value: unknown, secretKeys: readonly string[]): unknown;
+}
+export declare const envStoreToken: import("@zhin.js/plugin-runtime").Token<EnvStore>;
+export declare class EnvironmentVariableMissingError extends Error {
+    readonly owner: PluginId;
+    readonly key: string;
+    constructor(owner: PluginId, key: string);
+}
+export declare class EnvSchemaParseError extends Error {
+    readonly owner: PluginId;
+    constructor(owner: PluginId, message: string);
+}
+export declare function defineEnvSchema<T>(schema: EnvSchema<T>): Readonly<EnvSchema<T>>;
+export declare function defineEnvironmentLayers(layers?: EnvironmentLayers): Readonly<EnvironmentLayers>;
+export declare function createEnvStore(owner: PluginId, environment: RuntimeEnvironment, layers?: EnvironmentLayers): EnvStore;
+/** Normalizes layers once, then derives immutable stores for each Plugin owner. */
+export declare class EnvStoreFactory {
+    #private;
+    constructor(environment: RuntimeEnvironment, layers?: EnvironmentLayers);
+    create(owner: PluginId): EnvStore;
+}
+/**
+ * Standalone deep expansion over an arbitrary config value (e.g. a raw `ai`
+ * config document before EnvStore scoping exists). Supports `${VAR}` and
+ * `${VAR:-default}` / `${VAR:=default}` (default applies when the variable is
+ * unset or empty). Missing plain references resolve via `onMissing`
+ * (default: `""`, matching `EnvStore.expandMissingAsEmpty`).
+ */
+export declare function expandEnvironmentValue<T>(value: T, lookup: (key: string) => string | undefined, onMissing?: (key: string) => string): T;