@zhin.js/plugin-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,29 @@
+# @zhin.js/plugin-runtime
+
+Zhin Plugin-first 架构的零生产依赖底座。它定义 Plugin tree、Scope、Capability Slot、
+不可变 RuntimeSnapshot、generation lease、handoff 与 RootController，不理解 IM、Agent、
+配置格式、文件发现或构建工具。
+
+```ts
+import {
+  createToken,
+  definePlugin,
+  RootController,
+} from '@zhin.js/plugin-runtime';
+```
+
+## 生命周期
+
+```text
+prepare shadow state -> validate -> handoff -> atomic commit
+  -> new work leases new snapshot -> old generation drains -> dispose
+```
+
+局部 HMR 只缩小 prepare/setup/dispose 范围；每次 commit 始终发布完整一致的 snapshot。
+长期 socket、worker 或 admission loop 必须参加 generation handoff，不能成为模块级副作用。
+
+本包没有生产依赖。YAML、AJV、watcher、IM 与 AI 都属于上层 adapter 或 Runtime。
+
+验证：`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/capability.d.ts

@@ -0,0 +1,10 @@
+import { type CapabilityId, type FeatureId, type PluginId } from './identity.js';
+export interface CapabilitySlot<T = unknown> {
+    readonly id: CapabilityId;
+    readonly owner: PluginId;
+    readonly feature: FeatureId;
+    readonly localName: string;
+    readonly source: string;
+    readonly definition: T;
+}
+export declare function createCapabilitySlot<T>(input: Omit<CapabilitySlot<T>, 'id'>): Readonly<CapabilitySlot<T>>;

package/lib/capability.js

@@ -0,0 +1,7 @@
+import { capabilityId, } from './identity.js';
+export function createCapabilitySlot(input) {
+    return Object.freeze({
+        ...input,
+        id: capabilityId(input.owner, input.feature, input.localName),
+    });
+}

package/lib/database-host.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Minimal model surface shared by lottery / rss / group-suite memory stores
+ * and the Host-backed `@zhin.js/database` adapter.
+ */
+export interface DatabaseHostModel {
+    select(): {
+        where(query: Record<string, unknown>): Promise<Record<string, unknown>[]>;
+        then<TResult1 = Record<string, unknown>[], TResult2 = never>(onfulfilled?: ((value: Record<string, unknown>[]) => TResult1 | PromiseLike<TResult1>) | null, onrejected?: ((reason: unknown) => TResult2 | PromiseLike<TResult2>) | null): Promise<TResult1 | TResult2>;
+    };
+    insert(row: Record<string, unknown>): Promise<unknown>;
+    delete(): {
+        where(query: Record<string, unknown>): Promise<unknown>;
+    };
+    update(patch: Record<string, unknown>): {
+        where(query: Record<string, unknown>): Promise<unknown>;
+    };
+}
+export type DatabaseHostType = 'related' | 'document' | 'keyvalue';
+export interface DatabaseHostTable {
+    readonly name: string;
+    readonly columns?: Readonly<Record<string, unknown>>;
+}
+export interface DatabaseHostSelectResult {
+    readonly rows: readonly unknown[];
+    readonly total: number;
+    readonly page: number;
+    readonly pageSize: number;
+}
+/** Root-only database administration surface used by Console RPC. */
+export interface DatabaseHostConsole {
+    info(): {
+        readonly dialect: string;
+        readonly type: DatabaseHostType;
+        readonly tables: readonly string[];
+        readonly connected: boolean;
+    };
+    tables(): readonly DatabaseHostTable[];
+    select(table: string, page: number, pageSize: number, where?: Record<string, unknown>): Promise<DatabaseHostSelectResult>;
+    insert(table: string, row: Record<string, unknown>): Promise<void>;
+    update(table: string, row: Record<string, unknown>, where: Record<string, unknown>): Promise<unknown>;
+    delete(table: string, where: Record<string, unknown>): Promise<unknown>;
+    dropTable(table: string): Promise<void>;
+    kvGet(table: string, key: string): Promise<unknown>;
+    kvSet(table: string, key: string, value: unknown, ttl?: number): Promise<void>;
+    kvDelete(table: string, key: string): Promise<void>;
+    kvEntries(table: string): Promise<readonly {
+        key: string;
+        value: unknown;
+    }[]>;
+}
+/**
+ * Thin Host Resource for Plugin Runtime persistence.
+ * Plugins call `define` during `setup()`; Host starts the dialect on generation
+ * `activateNext` so models are available before commands / cron run.
+ */
+export interface DatabaseHost {
+    readonly dialect: string;
+    readonly started: boolean;
+    /** Register a table schema before `start` (column defs match `@zhin.js/database`). */
+    define(name: string, definition: Record<string, unknown>): void;
+    /** Names of tables registered via `define` (Console `db:tables`). */
+    tables(): readonly string[];
+    models: {
+        get(name: string): DatabaseHostModel | undefined;
+    };
+    /** Root-only management port; absent on lightweight test/memory hosts. */
+    readonly console?: DatabaseHostConsole;
+    /**
+     * Raw `@zhin.js/database` registry (full `create` / `select` API).
+     * Available after `start()` — used by Agent Host ADR 0009 persistence.
+     */
+    getRawDatabase(): {
+        models?: Map<string, unknown>;
+    } | undefined;
+    start(): Promise<void>;
+    stop(): Promise<void>;
+}
+export declare const databaseHostToken: import("./token.js").Token<DatabaseHost>;

package/lib/database-host.js

@@ -0,0 +1,2 @@
+import { createToken } from './token.js';
+export const databaseHostToken = createToken('zhin.database.host', 'Plugin Runtime database host');

package/lib/dispose.d.ts

@@ -0,0 +1,7 @@
+export type Dispose = () => void | Promise<void>;
+export declare class DisposeStack {
+    #private;
+    add(dispose: Dispose): Dispose;
+    seal(): void;
+    dispose(): Promise<void>;
+}

package/lib/dispose.js

@@ -0,0 +1,36 @@
+export class DisposeStack {
+    #items = [];
+    #sealed = false;
+    #disposed = false;
+    add(dispose) {
+        if (this.#sealed)
+            throw new Error('DisposeStack is sealed');
+        if (this.#disposed)
+            throw new Error('DisposeStack is disposed');
+        this.#items.push(dispose);
+        return dispose;
+    }
+    seal() {
+        if (this.#disposed)
+            throw new Error('DisposeStack is disposed');
+        this.#sealed = true;
+    }
+    async dispose() {
+        if (this.#disposed)
+            return;
+        this.#disposed = true;
+        this.#sealed = true;
+        const errors = [];
+        for (const dispose of this.#items.splice(0).reverse()) {
+            try {
+                await dispose();
+            }
+            catch (error) {
+                errors.push(error);
+            }
+        }
+        if (errors.length > 0) {
+            throw new AggregateError(errors, 'One or more disposers failed');
+        }
+    }
+}

package/lib/handoff.d.ts

@@ -0,0 +1,30 @@
+import type { RuntimeSnapshot } from './snapshot.js';
+export interface GenerationHandoff {
+    quiescePrevious(previous: RuntimeSnapshot): void | Promise<void>;
+    activateNext(): void | Promise<void>;
+    deactivateNext(): void | Promise<void>;
+    resumePrevious(): void | Promise<void>;
+    openNext(): void;
+}
+export interface GenerationHandoffParticipant {
+    quiescePrevious?(previous: RuntimeSnapshot): void | Promise<void>;
+    activateNext?(): void | Promise<void>;
+    deactivateNext?(): void | Promise<void>;
+    resumePrevious?(): void | Promise<void>;
+    openNext?(): void;
+}
+export interface GenerationHandoffRegistry {
+    add(participant: GenerationHandoffParticipant): GenerationHandoffParticipant;
+}
+/** Composes owner-ordered Resource handoffs and compensates partial progress. */
+export declare class GenerationHandoffStack implements GenerationHandoffRegistry, GenerationHandoff {
+    #private;
+    get size(): number;
+    add(participant: GenerationHandoffParticipant): GenerationHandoffParticipant;
+    seal(): GenerationHandoff | undefined;
+    quiescePrevious(previous: RuntimeSnapshot): Promise<void>;
+    activateNext(): Promise<void>;
+    deactivateNext(): Promise<void>;
+    resumePrevious(): Promise<void>;
+    openNext(): void;
+}

package/lib/handoff.js

@@ -0,0 +1,96 @@
+import { DisposeStack } from './dispose.js';
+/** Composes owner-ordered Resource handoffs and compensates partial progress. */
+export class GenerationHandoffStack {
+    #participants = [];
+    #quiesced = [];
+    #activated = [];
+    #sealed = false;
+    get size() {
+        return this.#participants.length;
+    }
+    add(participant) {
+        if (this.#sealed)
+            throw new Error('GenerationHandoffStack is sealed');
+        this.#participants.push(participant);
+        return participant;
+    }
+    seal() {
+        this.#sealed = true;
+        return this.size > 0 ? this : undefined;
+    }
+    async quiescePrevious(previous) {
+        this.#assertSealed();
+        try {
+            for (const participant of [...this.#participants].reverse()) {
+                if (!participant.quiescePrevious)
+                    continue;
+                await participant.quiescePrevious(previous);
+                this.#quiesced.push(participant);
+            }
+        }
+        catch (error) {
+            await compensate(error, () => this.resumePrevious(), 'Quiesce and resume both failed');
+        }
+    }
+    async activateNext() {
+        this.#assertSealed();
+        try {
+            for (const participant of this.#participants) {
+                if (!participant.activateNext)
+                    continue;
+                await participant.activateNext();
+                this.#activated.push(participant);
+            }
+        }
+        catch (error) {
+            await compensate(error, () => this.deactivateNext(), 'Activation and deactivation both failed');
+        }
+    }
+    async deactivateNext() {
+        await unwind(this.#activated, (participant) => participant.deactivateNext?.(), 'One or more next-generation Resources failed to deactivate');
+    }
+    async resumePrevious() {
+        await unwind(this.#quiesced, (participant) => participant.resumePrevious?.(), 'One or more previous-generation Resources failed to resume');
+    }
+    openNext() {
+        const errors = [];
+        for (const participant of this.#participants) {
+            try {
+                participant.openNext?.();
+            }
+            catch (error) {
+                errors.push(error);
+            }
+        }
+        if (errors.length > 0)
+            throw new AggregateError(errors, 'One or more Resources failed to open');
+    }
+    #assertSealed() {
+        if (!this.#sealed)
+            throw new Error('GenerationHandoffStack is not sealed');
+    }
+}
+async function compensate(primary, rollback, message) {
+    try {
+        await rollback();
+    }
+    catch (rollbackError) {
+        throw new AggregateError([primary, rollbackError], message, { cause: rollbackError });
+    }
+    throw primary;
+}
+async function unwind(completed, run, message) {
+    const disposers = new DisposeStack();
+    for (const participant of completed.splice(0)) {
+        disposers.add(() => run(participant));
+    }
+    try {
+        await disposers.dispose();
+    }
+    catch (error) {
+        if (error instanceof AggregateError) {
+            throw new AggregateError(error.errors, message, { cause: error });
+        }
+        throw error;
+    }
+}

package/lib/html-renderer.d.ts

@@ -0,0 +1,23 @@
+export interface HtmlRenderOptions {
+    readonly width?: number;
+    readonly format?: 'png' | 'svg';
+    readonly backgroundColor?: string;
+}
+export interface HtmlRenderResult {
+    /** PNG 时为 Buffer/Uint8Array，SVG 时为 string。 */
+    readonly data: unknown;
+    readonly format: 'png' | 'svg';
+    readonly width: number;
+    readonly height: number;
+    readonly mimeType: string;
+}
+/**
+ * Thin Host Resource for Plugin Runtime outbound html→image rendering.
+ * Implemented by the optional `@zhin.js/html-renderer` package (wired by the
+ * CLI Host); absent when the package is not installed — consumers must fall
+ * back to plain text.
+ */
+export interface HtmlRendererHost {
+    render(html: string, options?: HtmlRenderOptions): Promise<HtmlRenderResult>;
+}
+export declare const htmlRendererToken: import("./token.js").Token<HtmlRendererHost>;

package/lib/html-renderer.js

@@ -0,0 +1,2 @@
+import { createToken } from './token.js';
+export const htmlRendererToken = createToken('zhin.html-renderer.host', 'Plugin Runtime html → image renderer host');

package/lib/identity.d.ts

@@ -0,0 +1,22 @@
+declare const tokenIdBrand: unique symbol;
+declare const pluginIdBrand: unique symbol;
+declare const featureIdBrand: unique symbol;
+declare const capabilityIdBrand: unique symbol;
+export type TokenId = string & {
+    readonly [tokenIdBrand]: true;
+};
+export type PluginId = string & {
+    readonly [pluginIdBrand]: true;
+};
+export type FeatureId = string & {
+    readonly [featureIdBrand]: true;
+};
+export type CapabilityId = string & {
+    readonly [capabilityIdBrand]: true;
+};
+export declare function tokenId(value: string): TokenId;
+export declare function featureId(value: string): FeatureId;
+export declare function rootPluginId(): PluginId;
+export declare function childPluginId(parent: PluginId, instanceKey: string): PluginId;
+export declare function capabilityId(owner: PluginId, feature: FeatureId, localName: string): CapabilityId;
+export {};

package/lib/identity.js

@@ -0,0 +1,32 @@
+const namespacePattern = /^[a-z][a-z0-9.-]*$/;
+const localNamePattern = /^[a-z0-9][a-z0-9-]*$/;
+const capabilityLocalSegment = String.raw `(?:[a-z0-9][a-z0-9-]*|\$[a-z][a-zA-Z0-9]*)`;
+const capabilityLocalNamePattern = new RegExp(`^${capabilityLocalSegment}(?:/${capabilityLocalSegment})*$`);
+function assertNamespace(value, label) {
+    if (!namespacePattern.test(value)) {
+        throw new TypeError(`Invalid ${label}: ${value}`);
+    }
+}
+export function tokenId(value) {
+    assertNamespace(value, 'token id');
+    return value;
+}
+export function featureId(value) {
+    assertNamespace(value, 'feature id');
+    return value;
+}
+export function rootPluginId() {
+    return 'root';
+}
+export function childPluginId(parent, instanceKey) {
+    if (!localNamePattern.test(instanceKey)) {
+        throw new TypeError(`Invalid plugin instance key: ${instanceKey}`);
+    }
+    return `${parent}/${instanceKey}`;
+}
+export function capabilityId(owner, feature, localName) {
+    if (!capabilityLocalNamePattern.test(localName)) {
+        throw new TypeError(`Invalid capability local name: ${localName}`);
+    }
+    return `${owner}\0${feature}\0${localName}`;
+}

package/lib/index.d.ts

@@ -0,0 +1,13 @@
+export * from './capability.js';
+export * from './dispose.js';
+export * from './identity.js';
+export * from './handoff.js';
+export * from './plugin.js';
+export * from './root-controller.js';
+export * from './shared-lifetime.js';
+export * from './snapshot.js';
+export * from './token.js';
+export * from './schedule-host.js';
+export * from './database-host.js';
+export * from './html-renderer.js';
+export * from './outbound-host.js';

package/lib/index.js

@@ -0,0 +1,13 @@
+export * from './capability.js';
+export * from './dispose.js';
+export * from './identity.js';
+export * from './handoff.js';
+export * from './plugin.js';
+export * from './root-controller.js';
+export * from './shared-lifetime.js';
+export * from './snapshot.js';
+export * from './token.js';
+export * from './schedule-host.js';
+export * from './database-host.js';
+export * from './html-renderer.js';
+export * from './outbound-host.js';

package/lib/outbound-host.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Thin Host Resource for proactive Adapter outbound (RSS poll, lottery push,
+ * activity-feedback typing text). Implementations typically wrap ImRuntime
+ * `sendEndpointMessage` (resolve adapter/endpoint → AdapterIndex.send).
+ */
+export interface OutboundSendInput {
+    readonly adapter: string;
+    readonly endpointId: string;
+    readonly channelType: string;
+    readonly channelId: string;
+    readonly content: string;
+}
+export interface OutboundReactionInput {
+    readonly adapter: string;
+    readonly endpointId: string;
+    readonly messageId: string;
+    readonly emoji: string;
+    readonly sceneType?: string;
+    readonly channelId?: string;
+}
+export interface OutboundRemoveReactionInput {
+    readonly adapter: string;
+    readonly endpointId: string;
+    readonly messageId: string;
+    readonly reactionId: string;
+}
+export interface OutboundRecallInput {
+    readonly adapter: string;
+    readonly endpointId: string;
+    readonly messageId: string;
+}
+export interface OutboundHost {
+    /** Returns platform message id when available (activity-feedback needs it). */
+    send(input: OutboundSendInput): Promise<string | null>;
+    /** Optional: platform message reactions (icqq group emoji, etc.). */
+    addReaction?(input: OutboundReactionInput): Promise<string | null>;
+    removeReaction?(input: OutboundRemoveReactionInput): Promise<void>;
+    /** Optional: recall/delete a status message (activity-feedback autoRemove). */
+    recall?(input: OutboundRecallInput): Promise<void>;
+}
+export declare const outboundHostToken: import("./token.js").Token<OutboundHost>;

package/lib/outbound-host.js

@@ -0,0 +1,2 @@
+import { createToken } from './token.js';
+export const outboundHostToken = createToken('zhin.outbound.host', 'Plugin Runtime outbound push host');

package/lib/plugin.d.ts

@@ -0,0 +1,33 @@
+import type { Dispose, DisposeStack } from './dispose.js';
+import type { GenerationHandoffRegistry } from './handoff.js';
+import type { PluginId } from './identity.js';
+import type { Scope, Token } from './token.js';
+export interface PluginMetadata {
+    readonly displayName?: string;
+    readonly icon?: string;
+    readonly order?: number;
+}
+export interface ConfigView<T> {
+    get(): Readonly<T>;
+}
+export interface PluginInstanceView {
+    readonly id: PluginId;
+    readonly instanceKey: string;
+    readonly parent?: PluginId;
+    readonly root: PluginId;
+    readonly role: 'root' | 'child';
+}
+export interface PluginSetupContext<TConfig = unknown> {
+    readonly plugin: PluginInstanceView;
+    readonly config: ConfigView<TConfig>;
+    readonly resources: Scope;
+    readonly lifecycle: DisposeStack;
+    readonly handoff: GenerationHandoffRegistry;
+}
+export interface PluginDefinition<TConfig = unknown> {
+    readonly name: string;
+    readonly metadata?: PluginMetadata;
+    readonly requires?: readonly Token<unknown>[];
+    setup?(context: PluginSetupContext<TConfig>): void | Dispose | Promise<void | Dispose>;
+}
+export declare function definePlugin<TConfig = unknown>(definition: PluginDefinition<TConfig>): Readonly<PluginDefinition<TConfig>>;

package/lib/plugin.js

@@ -0,0 +1,11 @@
+const pluginNamePattern = /^[a-z][a-z0-9-]*$/;
+export function definePlugin(definition) {
+    if (!pluginNamePattern.test(definition.name)) {
+        throw new TypeError(`Invalid plugin name: ${definition.name}`);
+    }
+    return Object.freeze({
+        ...definition,
+        metadata: definition.metadata ? Object.freeze({ ...definition.metadata }) : undefined,
+        requires: Object.freeze([...(definition.requires ?? [])]),
+    });
+}

package/lib/root-controller.d.ts

@@ -0,0 +1,18 @@
+import type { PluginId } from './identity.js';
+import { SnapshotStore, type PreparedGeneration, type RuntimeSnapshot, type SnapshotState } from './snapshot.js';
+export type RootState = 'idle' | 'running' | 'stopping' | 'stopped' | 'failed';
+export type PrepareGeneration = (current: RuntimeSnapshot) => PreparedGeneration | Promise<PreparedGeneration>;
+export type PrepareTransaction = (current: RuntimeSnapshot) => PreparedGeneration | undefined | Promise<PreparedGeneration | undefined>;
+export type ControlErrorHandler = (error: unknown) => void;
+export declare class RootController {
+    #private;
+    private readonly onControlError;
+    readonly snapshots: SnapshotStore;
+    constructor(initial: SnapshotState, onControlError?: ControlErrorHandler);
+    get state(): RootState;
+    get generation(): number;
+    start(prepare: PrepareGeneration): Promise<RuntimeSnapshot>;
+    transact(prepare: PrepareTransaction): Promise<RuntimeSnapshot>;
+    reload(_target: PluginId | string, prepare: PrepareTransaction): Promise<RuntimeSnapshot>;
+    stop(): Promise<void>;
+}

package/lib/root-controller.js

@@ -0,0 +1,140 @@
+import { SnapshotStore, } from './snapshot.js';
+export class RootController {
+    onControlError;
+    snapshots;
+    #state = 'idle';
+    #tail = Promise.resolve();
+    constructor(initial, onControlError = () => undefined) {
+        this.onControlError = onControlError;
+        this.snapshots = new SnapshotStore(initial);
+    }
+    get state() {
+        return this.#state;
+    }
+    get generation() {
+        return this.snapshots.current.generation;
+    }
+    start(prepare) {
+        return this.#enqueue(async () => {
+            if (this.#state !== 'idle') {
+                throw new Error(`Cannot start RootController from ${this.#state}`);
+            }
+            let prepared;
+            let activated = false;
+            try {
+                prepared = await prepare(this.snapshots.current);
+                if (prepared.handoff) {
+                    activated = true;
+                    await prepared.handoff.activateNext();
+                }
+                const handoff = prepared.handoff;
+                const snapshot = this.snapshots.commit(0, prepared);
+                prepared = undefined;
+                this.#state = 'running';
+                this.#openNext(handoff);
+                return snapshot;
+            }
+            catch (error) {
+                this.#state = 'failed';
+                return this.#rollback(prepared, { activated }, error);
+            }
+        });
+    }
+    transact(prepare) {
+        return this.#enqueue(async () => {
+            if (this.#state !== 'running') {
+                throw new Error(`Cannot transact RootController from ${this.#state}`);
+            }
+            const previous = this.snapshots.acquire();
+            let prepared;
+            let quiesced = false;
+            let activated = false;
+            try {
+                prepared = await prepare(previous.value);
+                if (!prepared)
+                    return previous.value;
+                if (prepared.handoff) {
+                    quiesced = true;
+                    await prepared.handoff.quiescePrevious(previous.value);
+                    activated = true;
+                    await prepared.handoff.activateNext();
+                }
+                const handoff = prepared.handoff;
+                const snapshot = this.snapshots.commit(previous.value.generation, prepared);
+                prepared = undefined;
+                this.#openNext(handoff);
+                return snapshot;
+            }
+            catch (error) {
+                return this.#rollback(prepared, { quiesced, activated }, error);
+            }
+            finally {
+                previous.release();
+            }
+        });
+    }
+    reload(_target, prepare) {
+        return this.transact(prepare);
+    }
+    stop() {
+        return this.#enqueue(async () => {
+            if (this.#state === 'stopped')
+                return;
+            if (this.#state !== 'running' && this.#state !== 'failed') {
+                throw new Error(`Cannot stop RootController from ${this.#state}`);
+            }
+            this.#state = 'stopping';
+            await this.snapshots.close();
+            this.#state = 'stopped';
+        });
+    }
+    #enqueue(operation) {
+        const result = this.#tail.then(operation, operation);
+        this.#tail = result.catch(() => undefined);
+        return result;
+    }
+    #openNext(handoff) {
+        try {
+            handoff?.openNext();
+        }
+        catch (error) {
+            try {
+                this.onControlError(error);
+            }
+            catch {
+                // Error reporting cannot roll back an already committed generation.
+            }
+        }
+    }
+    async #rollback(prepared, state, transactionError) {
+        const errors = [transactionError];
+        if (prepared && state.activated) {
+            try {
+                await prepared.handoff?.deactivateNext();
+            }
+            catch (error) {
+                errors.push(error);
+            }
+        }
+        if (prepared && state.quiesced) {
+            try {
+                await prepared.handoff?.resumePrevious();
+            }
+            catch (error) {
+                errors.push(error);
+            }
+        }
+        if (prepared) {
+            try {
+                await prepared.dispose();
+            }
+            catch (error) {
+                errors.push(error);
+            }
+        }
+        if (errors.length > 1) {
+            throw new AggregateError(errors, 'Generation transaction and rollback both failed');
+        }
+        throw transactionError;
+    }
+}

package/lib/schedule-host.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Thin Host Resource for Plugin Runtime cron jobs.
+ * Implementations typically wrap `@zhin.js/schedule` CalendarScheduler (solar cron).
+ */
+export interface ScheduleJobRegistration {
+    readonly id: string;
+    /** 6-field solar cron: `秒 分 时 日 月 周` */
+    readonly cron: string;
+    readonly description?: string;
+    execute(): void | Promise<void>;
+}
+export interface ScheduleHost {
+    /** Register a solar cron job; returns disposer that cancels the job. */
+    register(job: ScheduleJobRegistration): () => void;
+    list(): readonly {
+        readonly id: string;
+        readonly cron: string;
+        readonly description?: string;
+    }[];
+}
+export declare const scheduleHostToken: import("./token.js").Token<ScheduleHost>;

package/lib/schedule-host.js

@@ -0,0 +1,2 @@
+import { createToken } from './token.js';
+export const scheduleHostToken = createToken('zhin.schedule.host', 'Plugin Runtime solar cron host');

package/lib/shared-lifetime.d.ts

@@ -0,0 +1,11 @@
+import type { Dispose } from './dispose.js';
+export interface LifetimeLease {
+    release(): Promise<void>;
+}
+export declare class SharedLifetime {
+    #private;
+    private readonly dispose;
+    constructor(dispose: Dispose);
+    get references(): number;
+    acquire(): LifetimeLease;
+}

package/lib/shared-lifetime.js

@@ -0,0 +1,31 @@
+export class SharedLifetime {
+    dispose;
+    #references = 0;
+    #closed = false;
+    #disposal;
+    constructor(dispose) {
+        this.dispose = dispose;
+    }
+    get references() {
+        return this.#references;
+    }
+    acquire() {
+        if (this.#closed)
+            throw new Error('SharedLifetime is closed');
+        this.#references += 1;
+        let released = false;
+        return {
+            release: async () => {
+                if (released)
+                    return this.#disposal;
+                released = true;
+                this.#references -= 1;
+                if (this.#references === 0) {
+                    this.#closed = true;
+                    this.#disposal = Promise.resolve().then(this.dispose);
+                }
+                await this.#disposal;
+            },
+        };
+    }
+}

package/lib/snapshot.d.ts

@@ -0,0 +1,50 @@
+import type { CapabilitySlot } from './capability.js';
+import type { Dispose } from './dispose.js';
+import type { GenerationHandoff } from './handoff.js';
+import type { CapabilityId, FeatureId, PluginId, TokenId } from './identity.js';
+import type { PluginMetadata } from './plugin.js';
+export interface PluginNodeSnapshot {
+    readonly id: PluginId;
+    readonly instanceKey: string;
+    readonly packageName: string;
+    readonly packageRoot: string;
+    readonly parent?: PluginId;
+    readonly children: readonly PluginId[];
+    readonly metadata?: PluginMetadata;
+}
+export interface RuntimeSnapshot {
+    readonly generation: number;
+    readonly root: PluginId;
+    readonly tree: ReadonlyMap<PluginId, PluginNodeSnapshot>;
+    readonly config: ReadonlyMap<PluginId, unknown>;
+    readonly resources: ReadonlyMap<PluginId, ReadonlyMap<TokenId, unknown>>;
+    readonly capabilities: ReadonlyMap<CapabilityId, CapabilitySlot>;
+    readonly projections: ReadonlyMap<FeatureId, unknown>;
+}
+export type SnapshotState = Omit<RuntimeSnapshot, 'generation'>;
+export interface PreparedGeneration {
+    readonly snapshot: SnapshotState;
+    readonly dispose: Dispose;
+    readonly handoff?: GenerationHandoff;
+}
+export declare class GenerationConflictError extends Error {
+    readonly expected: number;
+    readonly actual: number;
+    constructor(expected: number, actual: number);
+}
+export declare class SnapshotLease {
+    #private;
+    readonly value: RuntimeSnapshot;
+    private readonly releaseRecord;
+    constructor(value: RuntimeSnapshot, releaseRecord: () => void);
+    release(): void;
+}
+export declare class SnapshotStore {
+    #private;
+    constructor(initial: SnapshotState);
+    get current(): RuntimeSnapshot;
+    acquire(): SnapshotLease;
+    commit(expectedGeneration: number, prepared: PreparedGeneration): RuntimeSnapshot;
+    close(): Promise<void>;
+}
+export declare function createSnapshotView(generation: number, state: SnapshotState): RuntimeSnapshot;

package/lib/snapshot.js

@@ -0,0 +1,155 @@
+export class GenerationConflictError extends Error {
+    expected;
+    actual;
+    constructor(expected, actual) {
+        super(`Generation conflict: expected ${expected}, actual ${actual}`);
+        this.expected = expected;
+        this.actual = actual;
+        this.name = 'GenerationConflictError';
+    }
+}
+export class SnapshotLease {
+    value;
+    releaseRecord;
+    #released = false;
+    constructor(value, releaseRecord) {
+        this.value = value;
+        this.releaseRecord = releaseRecord;
+    }
+    release() {
+        if (this.#released)
+            return;
+        this.#released = true;
+        this.releaseRecord();
+    }
+}
+export class SnapshotStore {
+    #current;
+    #retired = new Set();
+    #closed = false;
+    constructor(initial) {
+        this.#current = {
+            snapshot: createSnapshotView(0, initial),
+            dispose: () => undefined,
+            leases: 0,
+            retired: false,
+        };
+    }
+    get current() {
+        return this.#current.snapshot;
+    }
+    acquire() {
+        if (this.#closed)
+            throw new Error('SnapshotStore is closed');
+        const record = this.#current;
+        record.leases += 1;
+        return new SnapshotLease(record.snapshot, () => {
+            record.leases -= 1;
+            this.#disposeIfReady(record);
+        });
+    }
+    commit(expectedGeneration, prepared) {
+        // The caller owns a candidate until this method succeeds. This lets the
+        // transaction authority undo handoff state before disposing a rejection.
+        if (this.#closed) {
+            throw new Error('SnapshotStore is closed');
+        }
+        if (this.#current.snapshot.generation !== expectedGeneration) {
+            throw new GenerationConflictError(expectedGeneration, this.#current.snapshot.generation);
+        }
+        const previous = this.#current;
+        // Commit only swaps the active pointer. The previous record may still be
+        // serving in-flight work, so disposal is deferred to its final lease.
+        this.#current = {
+            snapshot: createSnapshotView(expectedGeneration + 1, prepared.snapshot),
+            dispose: prepared.dispose,
+            leases: 0,
+            retired: false,
+        };
+        previous.retired = true;
+        this.#retired.add(previous);
+        this.#disposeIfReady(previous);
+        return this.#current.snapshot;
+    }
+    async close() {
+        if (this.#closed)
+            return;
+        this.#closed = true;
+        this.#current.retired = true;
+        this.#retired.add(this.#current);
+        this.#disposeIfReady(this.#current);
+        // A Root is not stopped while any historical generation still owns live
+        // resources. This also surfaces deferred disposer failures to the caller.
+        await Promise.all([...this.#retired].map((record) => this.#waitForDisposal(record)));
+        this.#retired.clear();
+    }
+    #disposeIfReady(record) {
+        if (!record.retired || record.leases !== 0)
+            return;
+        if (!record.disposing) {
+            record.disposing = Promise.resolve().then(record.dispose);
+            void record.disposing.then(() => record.drain?.resolve(), (error) => record.drain?.reject(error));
+        }
+    }
+    #waitForDisposal(record) {
+        if (record.disposing)
+            return record.disposing;
+        if (!record.drain) {
+            let resolve;
+            let reject;
+            const promise = new Promise((onResolve, onReject) => {
+                resolve = onResolve;
+                reject = onReject;
+            });
+            record.drain = { promise, resolve, reject };
+        }
+        return record.drain.promise;
+    }
+}
+export function createSnapshotView(generation, state) {
+    // Object.freeze(Map) does not disable Map#set. ReadonlyMapView removes the
+    // mutator interface at runtime, including from provider projection hooks.
+    return Object.freeze({
+        ...state,
+        generation,
+        tree: readonlyMap(state.tree),
+        config: readonlyMap(state.config),
+        resources: readonlyMap([...state.resources].map(([owner, resources]) => [owner, readonlyMap(resources)])),
+        capabilities: readonlyMap(state.capabilities),
+        projections: readonlyMap(state.projections),
+    });
+}
+class ReadonlyMapView {
+    #values;
+    constructor(entries) {
+        this.#values = new Map(entries);
+        Object.freeze(this);
+    }
+    get size() {
+        return this.#values.size;
+    }
+    get(key) {
+        return this.#values.get(key);
+    }
+    has(key) {
+        return this.#values.has(key);
+    }
+    entries() {
+        return this.#values.entries();
+    }
+    keys() {
+        return this.#values.keys();
+    }
+    values() {
+        return this.#values.values();
+    }
+    forEach(callback) {
+        this.#values.forEach((value, key) => callback(value, key, this));
+    }
+    [Symbol.iterator]() {
+        return this.entries();
+    }
+}
+function readonlyMap(values) {
+    return new ReadonlyMapView(values);
+}

package/lib/token.d.ts

@@ -0,0 +1,20 @@
+import { DisposeStack, type Dispose } from './dispose.js';
+import { type PluginId, type TokenId } from './identity.js';
+export interface Token<T> {
+    readonly id: TokenId;
+    readonly description?: string;
+    readonly _type?: () => T;
+}
+export declare function createToken<T>(id: string, description?: string): Token<T>;
+export declare class Scope {
+    #private;
+    readonly owner: PluginId;
+    readonly parent?: Scope | undefined;
+    readonly disposers: DisposeStack;
+    constructor(owner: PluginId, parent?: Scope | undefined, disposers?: DisposeStack);
+    provide<T>(token: Token<T>, value: T, dispose?: Dispose): void;
+    use<T>(token: Token<T>): T;
+    has<T>(token: Token<T>): boolean;
+    seal(): void;
+    snapshot(): ReadonlyMap<TokenId, unknown>;
+}

package/lib/token.js

@@ -0,0 +1,52 @@
+import { DisposeStack } from './dispose.js';
+import { tokenId } from './identity.js';
+export function createToken(id, description) {
+    return Object.freeze({ id: tokenId(id), description });
+}
+export class Scope {
+    owner;
+    parent;
+    disposers;
+    #bindings = new Map();
+    #sealed = false;
+    constructor(owner, parent, disposers = new DisposeStack()) {
+        this.owner = owner;
+        this.parent = parent;
+        this.disposers = disposers;
+    }
+    provide(token, value, dispose) {
+        if (this.#sealed)
+            throw new Error(`Scope is sealed: ${this.owner}`);
+        if (this.#bindings.has(token.id)) {
+            throw new Error(`Duplicate resource ${token.id} in ${this.owner}`);
+        }
+        this.#bindings.set(token.id, Object.freeze({ owner: this.owner, value }));
+        if (dispose)
+            this.disposers.add(dispose);
+    }
+    use(token) {
+        const binding = this.#bindings.get(token.id);
+        if (binding)
+            return binding.value;
+        if (this.parent)
+            return this.parent.use(token);
+        throw new Error(`Missing resource ${token.id} for ${this.owner}`);
+    }
+    has(token) {
+        return this.#bindings.has(token.id) || Boolean(this.parent?.has(token));
+    }
+    seal() {
+        this.#sealed = true;
+        this.disposers.seal();
+    }
+    snapshot() {
+        if (!this.#sealed)
+            throw new Error(`Scope is not sealed: ${this.owner}`);
+        const result = this.parent
+            ? new Map(this.parent.snapshot())
+            : new Map();
+        for (const [id, binding] of this.#bindings)
+            result.set(id, binding.value);
+        return result;
+    }
+}

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@zhin.js/plugin-runtime",
+  "version": "1.0.0",
+  "description": "Zero-dependency Plugin tree, Scope and atomic generation runtime for Zhin",
+  "type": "module",
+  "main": "./lib/index.js",
+  "types": "./lib/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "development": "./src/index.ts",
+      "import": "./lib/index.js"
+    }
+  },
+  "files": [
+    "lib"
+  ],
+  "devDependencies": {
+    "@types/node": "^26.1.0",
+    "typescript": "^6.0.3"
+  },
+  "engines": {
+    "node": "^20.19.0 || >=22.12.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/zhinjs/zhin.git",
+    "directory": "packages/im/plugin-runtime"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  },
+  "license": "MIT",
+  "private": false,
+  "scripts": {
+    "build": "tsc",
+    "clean": "rimraf lib",
+    "test": "vitest run --root ../../.. packages/im/plugin-runtime/tests"
+  }
+}