@zhin.js/runtime 1.1.8 → 1.1.10

package/README.md

@@ -1,7 +1,7 @@
 # @zhin.js/runtime
 
-Zhin.js Plugin 树的 Root 生命周期权威。它从静态 package manifest 构建 Plugin instance
-tree，按 owner 组合 schema/config/env，通过 Feature provider 发现 capability，并用
+Zhin.js Plugin 树的 Root 生命周期权威。它从 `configVersion: 2` 应用声明创建 Root 直接实例，
+从包 manifest 读取 Feature/API 契约，按 owner 组合 schema/config/env，通过 Feature provider 发现 capability，并用
 immutable snapshot、CAS generation 与 lease 驱动局部 HMR。
 
 ```ts
@@ -10,17 +10,23 @@ import { EsmModuleRuntime, RootRuntime } from '@zhin.js/runtime';
 const runtime = new RootRuntime({
   projectRoot: process.cwd(),
   modules: new EsmModuleRuntime(),
-  environment: { mode: 'development' },
+  config: { configVersion: 2, plugins: {} },
+  environment: { name: 'development', mode: 'development', platform: 'node' },
 });
 
 await runtime.start();
 ```
 
+`plugins` 是实例名到包引用的映射；业务配置放在顶层同名块，停用实例列在 `disable_plugins`。
+Root 自身配置仍放在 `plugin`。缺少版本标记或 Root 包仍含非空 `zhin.plugins` 时会拒绝启动，
+迁移步骤见 [插件实例声明迁移](../../../docs/migrations/plugin-instance-declarations.md)。
+自定义 `config` resolver 通过 `application` 选项提供同一 v2 应用声明，不从包清单推断实例。
+
 ## 事务边界
 
 - capability 文件变化只 prepare 对应 Slot。
 - child/schema 变化替换最浅受影响 subtree。
-- manifest topology transaction 支持 child/Feature 新增、删除和移动。
+- 应用声明拓扑事务支持 Root 实例新增、删除和重排；Feature 挂载变更仍由包 manifest 驱动。
 - Root/package ABI、lockfile 和未知 importer 变化升级为 process restart。
 - 外部 Root 配置按实际投影分类：子 Plugin 配置只替换对应 subtree，Host 配置请求
   process restart。
@@ -41,3 +47,13 @@ pnpm --filter @zhin.js/runtime build
 pnpm --filter @zhin.js/runtime test
 pnpm --filter @zhin.js/runtime check:size
 ```
+
+
+## 配置解释的证据边界
+
+`PrimaryConfig.compositionMode` 由 RootRuntime 实际执行的配置合成分支记录为
+`document` 或 `custom`；没有标记的旧 authority 视为 `unknown`。它随原有
+PrimaryConfig generation 资源提交、保留和回滚，不记录配置值的历史来源。
+`createPrimaryConfig()` 未指定模式时使用 `unknown`，不能根据值相等推断模式。
+插件的最终 ConfigView 以同一 snapshot 的 `config.get(owner)` 为准；
+PrimaryConfig.expanded 使用 Root EnvStore，不能用其中的子段替代 child owner 的环境覆盖。

package/lib/application-plugin-declaration.d.ts

@@ -0,0 +1,17 @@
+/** Top-level names which cannot be used for a flat application Plugin instance. */
+export declare const APPLICATION_PLUGIN_RESERVED_KEYS: readonly string[];
+export interface ApplicationPluginInstanceDeclaration {
+    readonly instanceKey: string;
+    readonly package: string;
+    readonly enabled: boolean;
+}
+export type ApplicationPluginDeclaration = Readonly<{
+    version: 2;
+    instances: readonly ApplicationPluginInstanceDeclaration[];
+    disabled: readonly string[];
+}>;
+export declare const PLUGIN_INSTANCE_MIGRATION_GUIDE = "docs/migrations/plugin-instance-declarations.md";
+/** Reads the single supported application protocol; never guesses from business config. */
+export declare function readApplicationPluginDeclaration(document: Readonly<Record<string, unknown>>, source?: string, pluginOrder?: readonly string[]): ApplicationPluginDeclaration;
+/** Structural patch address for one instance's business configuration. */
+export declare function pluginInstanceConfigPath(document: Readonly<Record<string, unknown>>, instanceKey: string): readonly string[];

package/lib/application-plugin-declaration.js

@@ -0,0 +1,69 @@
+import hostConfigSchema from './host-config-schema.json' with { type: 'json' };
+/** Top-level names which cannot be used for a flat application Plugin instance. */
+export const APPLICATION_PLUGIN_RESERVED_KEYS = Object.freeze([
+    ...Object.keys(hostConfigSchema.properties),
+    'configVersion', 'plugins', 'disable_plugins', '__proto__', 'constructor', 'prototype',
+]);
+const reserved = new Set(APPLICATION_PLUGIN_RESERVED_KEYS);
+export const PLUGIN_INSTANCE_MIGRATION_GUIDE = 'docs/migrations/plugin-instance-declarations.md';
+/** Reads the single supported application protocol; never guesses from business config. */
+export function readApplicationPluginDeclaration(document, source = 'Root config', pluginOrder) {
+    if (document.configVersion !== 2) {
+        throw new TypeError(`${source}.configVersion must be 2; migrate the application configuration: ${PLUGIN_INSTANCE_MIGRATION_GUIDE}`);
+    }
+    const plugins = document.plugins === undefined ? {} : document.plugins;
+    if (!plugins || typeof plugins !== 'object' || Array.isArray(plugins)) {
+        throw new TypeError(`${source}.plugins must map instance aliases to package strings`);
+    }
+    const entries = plugins;
+    const keys = Object.keys(entries);
+    let order = keys;
+    if (pluginOrder) {
+        if (pluginOrder.length !== keys.length || new Set(pluginOrder).size !== keys.length
+            || pluginOrder.some(key => !Object.hasOwn(entries, key))) {
+            throw new TypeError(`${source} Plugin source order does not match plugins declarations`);
+        }
+        order = [...pluginOrder];
+    }
+    const disabled = document.disable_plugins === undefined ? [] : document.disable_plugins;
+    if (!Array.isArray(disabled) || disabled.some(key => typeof key !== 'string')) {
+        throw new TypeError(`${source}.disable_plugins must be an array of declared instance aliases`);
+    }
+    if (new Set(disabled).size !== disabled.length)
+        throw new TypeError(`${source}.disable_plugins contains duplicate aliases`);
+    for (const key of disabled) {
+        if (!Object.hasOwn(entries, key))
+            throw new TypeError(`${source}.disable_plugins references undeclared instance ${key}`);
+    }
+    const disabledKeys = new Set(disabled);
+    const instances = order.map(instanceKey => {
+        if (!/^[a-z0-9][a-z0-9-]*$/.test(instanceKey) || reserved.has(instanceKey)) {
+            throw new TypeError(`${source}.plugins has invalid or reserved instance alias ${instanceKey}`);
+        }
+        const reference = entries[instanceKey];
+        if (typeof reference !== 'string' || !isPluginPackageReference(reference)) {
+            throw new TypeError(`${source}.plugins.${instanceKey} must be a package name or package-relative ./ path`);
+        }
+        const config = document[instanceKey];
+        if (config !== undefined && (!config || typeof config !== 'object' || Array.isArray(config))) {
+            throw new TypeError(`${source}.${instanceKey} must be a Plugin business configuration object`);
+        }
+        return Object.freeze({ instanceKey, package: reference, enabled: !disabledKeys.has(instanceKey) });
+    });
+    for (const key of Object.keys(document)) {
+        if (!reserved.has(key) && !Object.hasOwn(entries, key))
+            throw new TypeError(`${source}.${key} is an undeclared Plugin configuration block`);
+    }
+    return Object.freeze({ version: 2, instances: Object.freeze(instances), disabled: Object.freeze([...disabled]) });
+}
+/** Structural patch address for one instance's business configuration. */
+export function pluginInstanceConfigPath(document, instanceKey) {
+    readApplicationPluginDeclaration(document);
+    return Object.freeze([instanceKey]);
+}
+function isPluginPackageReference(value) {
+    if (value.startsWith('./')) {
+        return value.length > 2 && !value.includes('\\') && !value.split('/').some(part => part === '..' || part === '');
+    }
+    return /^(?:@[a-z0-9][a-z0-9._-]*\/)?[a-z0-9][a-z0-9._-]*$/.test(value);
+}