@zhin.js/plugin-runtime 1.1.13 → 1.1.15

package/README.md

@@ -27,8 +27,20 @@ prepare shadow state -> validate -> handoff -> atomic commit
 局部 HMR 只缩小 prepare/setup/dispose 范围；每次 commit 始终发布完整一致的 snapshot。
 长期 socket、worker 或 admission loop 必须参加 generation handoff，不能成为模块级副作用。
 
+`SnapshotReader.acquire()` 返回的 `SnapshotLease.retirementSignal` 在该运行代被新一代替换、
+或 Root 关闭时同步触发，即使仍有 lease 持有旧资源。它供交互等待等需要随代结束的操作主动取消；
+不会代替 `lease.release()`、强制中断普通旧操作或提前销毁资源。被拒绝的候选不会触发当前代的信号。
+
 本包没有生产依赖。YAML、AJV、watcher、IM 与 AI 都属于上层 adapter 或 Runtime。
 
+## 可选管理员任务端口
+
+`PluginTaskProvider` 与 `pluginTaskProviderToken` 定义插件自己的管理员任务服务：插件通过 `provide()` 发布，Host 从当前运行代的所属 Scope 读取，不额外建立调度器。聊天发送者的个人任务不进入这个端口。
+
+任务快照包含真实任务、`revision` 与有界持久 `receipts`。创建或修改提交客户端操作 UUID 和原 `expectedRevision`；同一操作必须按相同内容幂等核对，不同内容复用 ID 或过期版本均应拒绝。回执确认的是持久命令，不是外部消息投递。未拿到响应时先只读核对，不能自动重发。服务必须携带 `generationAdmissionSource` 并参与实例退役。
+
+`PluginTaskError.message` 是可以向管理员展示的业务说明，不应含凭据或原始异常。Host 自己的输入、权限与运行代校验使用固定说明，普通异常不直接暴露。任务使用已有 `DeliveryTarget` 保留完整账号、会话、父容器与话题；`actions` 只列实际支持的操作，`unknown` 状态不能被包装成可安全重试。
+
 验证：`pnpm --filter @zhin.js/plugin-runtime test && pnpm --filter @zhin.js/plugin-runtime build`。
 
 详细契约见 [Kernel 与 Generation](../../../docs/architecture/target-implementation/kernel-and-generation.md)。

package/lib/index.d.ts

@@ -36,3 +36,4 @@ export * from './persistent-state.js';
 export * from './inbox.js';
 export * from './system-log.js';
 export * from './plugin-verification.js';
+export * from './plugin-tasks.js';

package/lib/index.js

@@ -36,3 +36,4 @@ export * from './persistent-state.js';
 export * from './inbox.js';
 export * from './system-log.js';
 export * from './plugin-verification.js';
+export * from './plugin-tasks.js';

package/lib/plugin-configuration.d.ts

@@ -1,4 +1,4 @@
-/** Canonical `zhin.config.*#plugins` shape keyed by Plugin instanceKey. */
+/** Plugin business configuration keyed by the aliases in a v2 application declaration. */
 export type PluginConfigurationMap = Readonly<Record<string, unknown>>;
 /** Raised when a Root config still uses a non-canonical Plugin configuration shape. */
 export declare class PluginConfigurationShapeError extends TypeError {
@@ -6,10 +6,6 @@ export declare class PluginConfigurationShapeError extends TypeError {
     constructor(source?: string);
 }
 /**
- * Reads the canonical Plugin instance configuration map.
- *
- * An omitted `plugins` key means that the Root has no configured child instances.
- * Every present value must be an object map; legacy package-name arrays belong only
- * to the explicit migration pipeline.
+ * Projects top-level business blocks for the declared application instances.
  */
 export declare function readPluginConfigurationMap(document: Readonly<Record<string, unknown>>, source?: string): PluginConfigurationMap;

package/lib/plugin-configuration.js

@@ -9,18 +9,20 @@ export class PluginConfigurationShapeError extends TypeError {
     }
 }
 /**
- * Reads the canonical Plugin instance configuration map.
- *
- * An omitted `plugins` key means that the Root has no configured child instances.
- * Every present value must be an object map; legacy package-name arrays belong only
- * to the explicit migration pipeline.
+ * Projects top-level business blocks for the declared application instances.
  */
 export function readPluginConfigurationMap(document, source = 'Root config') {
+    if (document.configVersion !== 2) {
+        throw new TypeError(`${source}.configVersion must be 2; see docs/migrations/plugin-instance-declarations.md`);
+    }
     const value = document.plugins;
     if (value === undefined)
         return EMPTY_PLUGIN_CONFIGURATION;
     if (!value || typeof value !== 'object' || Array.isArray(value)) {
         throw new PluginConfigurationShapeError(source);
     }
-    return value;
+    if (Object.values(value).some(reference => typeof reference !== 'string' || reference.length === 0)) {
+        throw new TypeError(`${source}.plugins must map instance aliases to package strings`);
+    }
+    return Object.freeze(Object.fromEntries(Object.keys(value).map(key => [key, document[key] === undefined ? {} : document[key]])));
 }

package/lib/plugin-tasks.d.ts

@@ -0,0 +1,62 @@
+import type { DeliveryTarget } from './delivery-target.js';
+import type { JsonValue } from './persistent-state.js';
+import type { GenerationAdmissionSource } from './admission.js';
+export type PluginTaskState = 'scheduled' | 'paused' | 'running' | 'unknown' | 'succeeded' | 'failed' | 'cancelled';
+export type PluginTaskAction = 'pause' | 'resume' | 'cancel' | 'update';
+/** Business task facts. Chat-user tasks are deliberately outside this administrator port. */
+export interface PluginTask {
+    readonly id: string;
+    readonly ownership: 'administrator';
+    readonly title: string;
+    readonly target: DeliveryTarget;
+    readonly state: PluginTaskState;
+    readonly createdAt: number;
+    readonly nextRunAt?: number;
+    readonly lastRunAt?: number;
+    readonly timezone?: string;
+    readonly detail?: string;
+    readonly parameters: Readonly<Record<string, JsonValue>>;
+    readonly actions: readonly PluginTaskAction[];
+}
+export interface PluginTaskSnapshot {
+    /** Changes whenever facts change. A stale mutation must fail instead of overwriting. */
+    readonly revision: string;
+    readonly tasks: readonly PluginTask[];
+    /** Bounded durable mutation acknowledgements, distinct from external delivery receipts. */
+    readonly receipts: readonly PluginTaskMutationReceipt[];
+}
+export interface PluginTaskMutationReceipt {
+    readonly requestId: string;
+    readonly taskId: string;
+    readonly operation: 'create' | PluginTaskAction;
+}
+export interface PluginTaskMutation {
+    /** Client-created operation UUID, retained for reconciliation after a lost response. */
+    readonly requestId: string;
+    readonly expectedRevision: string;
+}
+/** Optional plugin-owned task service, resolved from the current generation's owner scope. */
+export interface PluginTaskProvider extends GenerationAdmissionSource {
+    readonly title: string;
+    readonly description: string;
+    /** JSON Schema for this provider's creation/update parameters, never a Console-specific form. */
+    readonly schema: Readonly<Record<string, JsonValue>>;
+    /** Discloses future external effects before the operator creates a task. */
+    readonly effects: readonly string[];
+    read(): Promise<PluginTaskSnapshot>;
+    create(input: PluginTaskMutation & Readonly<{
+        target: DeliveryTarget;
+        parameters: Readonly<Record<string, JsonValue>>;
+    }>): Promise<PluginTaskSnapshot>;
+    change(input: PluginTaskMutation & Readonly<{
+        id: string;
+        action: PluginTaskAction;
+        parameters?: Readonly<Record<string, JsonValue>>;
+    }>): Promise<PluginTaskSnapshot>;
+}
+/** message is safe business guidance for administrators; never include secrets or raw exceptions. */
+export declare class PluginTaskError extends Error {
+    readonly code: 'invalid_input' | 'conflict' | 'not_found' | 'unsupported' | 'unavailable';
+    constructor(code: PluginTaskError['code'], message: string);
+}
+export declare const pluginTaskProviderToken: import("./token.js").Token<PluginTaskProvider>;

package/lib/plugin-tasks.js

@@ -0,0 +1,11 @@
+import { createToken } from './token.js';
+/** message is safe business guidance for administrators; never include secrets or raw exceptions. */
+export class PluginTaskError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = 'PluginTaskError';
+        this.code = code;
+    }
+}
+export const pluginTaskProviderToken = createToken('zhin.plugin-task-provider', 'Plugin-owned persistent administrator tasks, controlled only through authenticated Host operations');

package/lib/root-config-document.d.ts

@@ -10,10 +10,13 @@ export type ConfigPatch = {
 export interface ConfigDocumentSnapshot {
     readonly document: RuntimeConfigDocument;
     readonly revision: string;
+    /** v2 declaration aliases in source order, including integer-like keys. */
+    readonly pluginOrder?: readonly string[];
 }
 /** A prepared write is inert until the generation handoff activates it. */
 export interface PreparedConfigDocument {
     readonly document: RuntimeConfigDocument;
+    readonly pluginOrder?: readonly string[];
     commit(): Promise<ConfigDocumentSnapshot>;
     rollback(): Promise<void>;
 }

package/lib/snapshot.d.ts

@@ -50,7 +50,11 @@ export declare class SnapshotLease {
     #private;
     readonly value: RuntimeSnapshot;
     private readonly releaseRecord;
-    constructor(value: RuntimeSnapshot, releaseRecord: () => void, authority: typeof snapshotLeaseAuthority);
+    /** Aborted on publication of a replacement or Root close, before lease disposal. */
+    readonly retirementSignal: AbortSignal;
+    constructor(value: RuntimeSnapshot, releaseRecord: () => void, authority: typeof snapshotLeaseAuthority, 
+    /** Aborted on publication of a replacement or Root close, before lease disposal. */
+    retirementSignal: AbortSignal);
     get active(): boolean;
     release(): void;
 }

package/lib/snapshot.js

@@ -13,10 +13,14 @@ const snapshotLeaseAuthority = Symbol('SnapshotLeaseAuthority');
 export class SnapshotLease {
     value;
     releaseRecord;
+    retirementSignal;
     #released = false;
-    constructor(value, releaseRecord, authority) {
+    constructor(value, releaseRecord, authority, 
+    /** Aborted on publication of a replacement or Root close, before lease disposal. */
+    retirementSignal) {
         this.value = value;
         this.releaseRecord = releaseRecord;
+        this.retirementSignal = retirementSignal;
         if (authority !== snapshotLeaseAuthority)
             throw new TypeError('SnapshotLease is owned by SnapshotStore');
     }
@@ -43,6 +47,7 @@ export class SnapshotStore {
         const committed = Object.freeze({ snapshot, state: initialState });
         const admissions = collectSnapshotAdmissions(snapshot);
         const record = {
+            retirement: new AbortController(),
             snapshot,
             state: initialState,
             committed,
@@ -65,7 +70,7 @@ export class SnapshotStore {
         if (this.#closed)
             throw new Error('SnapshotStore is closed');
         const record = this.#current;
-        const lease = new SnapshotLease(record.snapshot, this.#retain(record), snapshotLeaseAuthority);
+        const lease = new SnapshotLease(record.snapshot, this.#retain(record), snapshotLeaseAuthority, record.retirement.signal);
         this.#leases.add(lease);
         return lease;
     }
@@ -87,6 +92,7 @@ export class SnapshotStore {
         const committed = Object.freeze({ snapshot, state });
         const admissions = collectSnapshotAdmissions(snapshot);
         const next = {
+            retirement: new AbortController(),
             snapshot,
             state,
             committed,
@@ -99,6 +105,7 @@ export class SnapshotStore {
         // Commit only swaps the active pointer. The previous record may still be
         // serving in-flight work, so disposal is deferred to its final lease.
         previous.retired = true;
+        previous.retirement.abort();
         this.#retired.add(previous);
         this.#disposeIfReady(previous);
         return this.#current.committed;
@@ -109,6 +116,7 @@ export class SnapshotStore {
         this.#closed = true;
         replaceGenerationAdmissions(this.#current.admissions, new Set(), this, () => undefined);
         this.#current.retired = true;
+        this.#current.retirement.abort();
         this.#retired.add(this.#current);
         this.#disposeIfReady(this.#current);
         // A Root is not stopped while any historical generation still owns live

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhin.js/plugin-runtime",
-  "version": "1.1.13",
+  "version": "1.1.15",
   "description": "Zero-dependency Plugin tree, Scope and atomic generation runtime for Zhin",
   "type": "module",
   "main": "./lib/index.js",
@@ -8,7 +8,6 @@
   "exports": {
     ".": {
       "types": "./lib/index.d.ts",
-      "development": "./src/index.ts",
       "import": "./lib/index.js"
     }
   },
@@ -20,7 +19,7 @@
     "typescript": "^6.0.3"
   },
   "engines": {
-    "node": "^20.19.0 || >=22.12.0"
+    "node": ">=22.19.0"
   },
   "repository": {
     "type": "git",