@zhin.js/plugin-runtime 1.1.8 → 1.1.10

package/lib/admission.d.ts

@@ -1,10 +1,5 @@
-/**
- * Ingress gate owned by a lifecycle Resource and switched only by SnapshotStore.
- * External callbacks may enter while the owning Resource is present in the
- * committed snapshot; candidate and retired Resources fail closed.
- */
 export declare class GenerationAdmissionGate {
-    constructor();
+    #private;
     get active(): boolean;
     acquire(): (() => void) | undefined;
     /** Observe the first commit which publishes this generation. */

package/lib/admission.js

@@ -1,32 +1,35 @@
-/**
- * Ingress gate owned by a lifecycle Resource and switched only by SnapshotStore.
- * External callbacks may enter while the owning Resource is present in the
- * committed snapshot; candidate and retired Resources fail closed.
- */
+// Assigned once by the class static block. The closures are a package-private
+// friend seam: lifecycle publication can mutate #private state without adding
+// Runtime-only methods to the public gate contract.
+let admissionLifecycle;
 export class GenerationAdmissionGate {
-    constructor() {
-        admissionState.set(this, { active: false });
-        admissionActivationListeners.set(this, new Set());
-        admissionDeactivationListeners.set(this, new Set());
+    #state = { active: false };
+    #owner;
+    #activationListeners = new Set();
+    #deactivationListeners = new Set();
+    static {
+        admissionLifecycle = {
+            assertClaimable: (gate, owner) => gate.#assertClaimable(owner),
+            assertOwner: (gate, owner) => gate.#assertOwner(owner),
+            claim: (gate, owner) => { gate.#owner = owner; },
+            activate: (gate, acquire) => gate.#activate(acquire),
+            deactivate: (gate) => gate.#deactivate(),
+        };
     }
     get active() {
-        return admissionState.get(this)?.active === true;
+        return this.#state.active;
     }
     acquire() {
-        const state = admissionState.get(this);
-        return state?.active ? state.acquire?.() : undefined;
+        return this.#state.active ? this.#state.acquire?.() : undefined;
     }
     /** Observe the first commit which publishes this generation. */
     onActivate(listener) {
-        const listeners = admissionActivationListeners.get(this);
-        if (!listeners)
-            throw new Error('Unknown generation admission gate');
         if (this.active) {
             listener();
             return () => undefined;
         }
-        listeners.add(listener);
-        return () => { listeners.delete(listener); };
+        this.#activationListeners.add(listener);
+        return () => { this.#activationListeners.delete(listener); };
     }
     /**
      * Observe retirement of the generation that owns this gate. The callback is
@@ -34,15 +37,12 @@ export class GenerationAdmissionGate {
      * ingress transports such as WebSocket connections.
      */
     onDeactivate(listener) {
-        const listeners = admissionDeactivationListeners.get(this);
-        if (!listeners)
-            throw new Error('Unknown generation admission gate');
         if (!this.active) {
             listener();
             return () => undefined;
         }
-        listeners.add(listener);
-        return () => { listeners.delete(listener); };
+        this.#deactivationListeners.add(listener);
+        return () => { this.#deactivationListeners.delete(listener); };
     }
     enter(operation) {
         const release = this.acquire();
@@ -60,11 +60,42 @@ export class GenerationAdmissionGate {
             throw error;
         }
     }
+    #assertClaimable(owner) {
+        if (this.#owner && this.#owner !== owner) {
+            throw new Error('Generation admission gate belongs to another SnapshotStore');
+        }
+    }
+    #assertOwner(owner) {
+        if (this.#owner !== owner) {
+            throw new Error('SnapshotStore does not own generation admission gate');
+        }
+    }
+    #activate(acquire) {
+        this.#state = { active: true, acquire };
+        for (const listener of this.#activationListeners) {
+            try {
+                listener();
+            }
+            catch {
+                // Admission publication is an infallible pointer switch. Buffered
+                // ingress reports through its own dispatch path.
+            }
+        }
+        this.#activationListeners.clear();
+    }
+    #deactivate() {
+        this.#state = { active: false };
+        for (const listener of this.#deactivationListeners) {
+            try {
+                listener();
+            }
+            catch {
+                // Admission publication is an infallible pointer switch. Transport
+                // cleanup reports through its own lifecycle and cannot veto commit.
+            }
+        }
+    }
 }
-const admissionState = new WeakMap();
-const admissionOwners = new WeakMap();
-const admissionActivationListeners = new WeakMap();
-const admissionDeactivationListeners = new WeakMap();
 export function createGenerationAdmissionGate() {
     return new GenerationAdmissionGate();
 }
@@ -103,50 +134,19 @@ export function replaceGenerationAdmissions(previous, next, owner, acquireNext)
     // Validate the complete switch before changing ownership or visibility. A
     // rejected cross-Root gate must leave both generations exactly untouched.
     for (const gate of next)
-        assertClaimableAdmission(gate, owner);
+        admissionLifecycle.assertClaimable(gate, owner);
     for (const gate of previous) {
-        assertAdmissionOwner(gate, owner);
+        admissionLifecycle.assertOwner(gate, owner);
     }
     for (const gate of next)
-        admissionOwners.set(gate, owner);
+        admissionLifecycle.claim(gate, owner);
     for (const gate of previous) {
         if (next.has(gate))
             continue;
-        admissionState.set(gate, { active: false });
-        for (const listener of admissionDeactivationListeners.get(gate) ?? []) {
-            try {
-                listener();
-            }
-            catch {
-                // Admission publication is an infallible pointer switch. Transport
-                // cleanup reports through its own lifecycle and cannot veto commit.
-            }
-        }
+        admissionLifecycle.deactivate(gate);
     }
     for (const gate of next) {
-        admissionState.set(gate, { active: true, acquire: acquireNext });
-        const listeners = admissionActivationListeners.get(gate);
-        for (const listener of listeners ?? []) {
-            try {
-                listener();
-            }
-            catch {
-                // Admission publication is an infallible pointer switch. Buffered
-                // ingress reports through its own dispatch path.
-            }
-        }
-        listeners?.clear();
-    }
-}
-function assertClaimableAdmission(gate, owner) {
-    const current = admissionOwners.get(gate);
-    if (current && current !== owner) {
-        throw new Error('Generation admission gate belongs to another SnapshotStore');
-    }
-}
-function assertAdmissionOwner(gate, owner) {
-    if (admissionOwners.get(gate) !== owner) {
-        throw new Error('SnapshotStore does not own generation admission gate');
+        admissionLifecycle.activate(gate, acquireNext);
     }
 }
 function isObject(value) {

package/lib/component-host.d.ts

@@ -39,7 +39,7 @@ export interface TemplateContext {
 /**
  * Thin Host Resource for Plugin Runtime outbound template compilation.
  * Evaluates `${expr}` template expressions in a sandboxed VM context
- * (same security boundary as the legacy ComponentFeature pipeline).
+ * The Host keeps render authority inside the active Runtime operation.
  *
  * Implemented by the CLI Host; absent when not wired — consumers must
  * pass text through unchanged.

package/lib/database-host.d.ts

@@ -1,4 +1,5 @@
-import { type PluginId } from './identity.js';
+import type { PluginId } from './identity.js';
+import { OwnerScopedResourceHost } from './owner-scoped-resource-host.js';
 export interface DatabaseHostSelection {
     where(query: Record<string, unknown>): DatabaseHostSelection;
     orderBy(field: string, direction?: 'ASC' | 'DESC'): DatabaseHostSelection;
@@ -96,32 +97,23 @@ export interface DatabaseHost {
  * the Runtime maps them to private physical table names before they reach the
  * process-wide DatabaseHost.
  */
-export interface PluginDatabaseHost {
-    readonly owner: PluginId;
-    readonly dialect: string;
-    readonly started: boolean;
-    define(name: string, definition: Record<string, unknown>): void;
-    tables(): readonly string[];
-    models: {
-        get(name: string): DatabaseHostModel | undefined;
-    };
-}
 /**
  * Maps a plugin's logical resource name to its process-wide physical name.
- * Root keeps its historical bare names so existing projects do not need a
- * database migration merely to adopt scoped child plugins.
+ * Every owner, including the root plugin, uses the same private namespace.
  */
 export declare function qualifyPluginResourceName(owner: PluginId, name: string): string;
-/** Reverse `qualifyPluginResourceName` only when the name belongs to owner. */
-export declare function unqualifyPluginResourceName(owner: PluginId, name: string): string | undefined;
-/** Creates a tenant facade without exposing Console administration or raw DB access. */
-export declare function createPluginDatabaseHost(owner: PluginId, host: DatabaseHost): PluginDatabaseHost;
-/**
- * Recovers a process host from the standard root token or a scoped facade.
- * This keeps custom RootRuntime installers written against the pre-facade
- * token working while child scopes begin receiving tenant boundaries.
- */
-export declare function unwrapPluginDatabaseHost(host: DatabaseHost | PluginDatabaseHost): DatabaseHost | undefined;
+/** Owner-bound persistence facade without Console administration or raw DB access. */
+export declare class PluginDatabaseHost extends OwnerScopedResourceHost {
+    private readonly host;
+    readonly models: {
+        get(name: string): DatabaseHostModel | undefined;
+    };
+    constructor(owner: PluginId, host: DatabaseHost);
+    get dialect(): string;
+    get started(): boolean;
+    define(name: string, definition: Record<string, unknown>): void;
+    tables(): readonly string[];
+}
 /**
  * Plugin-facing scoped persistence token. Runtime replaces this binding for
  * every Plugin Scope; plugin code must never receive the process-wide host.

package/lib/database-host.js

@@ -1,63 +1,40 @@
-import { pluginOwnerResourceKey, rootPluginId } from './identity.js';
+import { OwnerScopedResourceHost, qualifyOwnedResourceName, } from './owner-scoped-resource-host.js';
 import { createToken } from './token.js';
-const resourcePrefix = '__zhin_plugin__';
-const resourceSeparator = '__';
-const roots = new WeakMap();
 /**
- * Maps a plugin's logical resource name to its process-wide physical name.
- * Root keeps its historical bare names so existing projects do not need a
- * database migration merely to adopt scoped child plugins.
+ * Persistence surface visible to a plugin. Names are logical to the owner;
+ * the Runtime maps them to private physical table names before they reach the
+ * process-wide DatabaseHost.
  */
-export function qualifyPluginResourceName(owner, name) {
-    assertLogicalResourceName(name);
-    if (owner === rootPluginId())
-        return name;
-    return `${resourcePrefix}${pluginOwnerResourceKey(owner)}${resourceSeparator}${name}`;
-}
-/** Reverse `qualifyPluginResourceName` only when the name belongs to owner. */
-export function unqualifyPluginResourceName(owner, name) {
-    if (owner === rootPluginId())
-        return name.startsWith(resourcePrefix) ? undefined : name;
-    const prefix = `${resourcePrefix}${pluginOwnerResourceKey(owner)}${resourceSeparator}`;
-    return name.startsWith(prefix) ? name.slice(prefix.length) : undefined;
-}
-/** Creates a tenant facade without exposing Console administration or raw DB access. */
-export function createPluginDatabaseHost(owner, host) {
-    const facade = Object.freeze({
-        owner,
-        get dialect() { return host.dialect; },
-        get started() { return host.started; },
-        define(name, definition) {
-            host.define(qualifyPluginResourceName(owner, name), definition);
-        },
-        tables() {
-            return Object.freeze(host.tables().flatMap((name) => {
-                const logical = unqualifyPluginResourceName(owner, name);
-                return logical === undefined ? [] : [logical];
-            }));
-        },
-        models: Object.freeze({
-            get(name) {
-                return host.models.get(qualifyPluginResourceName(owner, name));
-            },
-        }),
-    });
-    roots.set(facade, host);
-    return facade;
-}
 /**
- * Recovers a process host from the standard root token or a scoped facade.
- * This keeps custom RootRuntime installers written against the pre-facade
- * token working while child scopes begin receiving tenant boundaries.
+ * Maps a plugin's logical resource name to its process-wide physical name.
+ * Every owner, including the root plugin, uses the same private namespace.
  */
-export function unwrapPluginDatabaseHost(host) {
-    if ('getRawDatabase' in host)
-        return host;
-    return roots.get(host);
+export function qualifyPluginResourceName(owner, name) {
+    return qualifyOwnedResourceName(owner, name);
 }
-function assertLogicalResourceName(name) {
-    if (!name || name.startsWith(resourcePrefix)) {
-        throw new TypeError(`Invalid plugin resource name: ${name}`);
+/** Owner-bound persistence facade without Console administration or raw DB access. */
+export class PluginDatabaseHost extends OwnerScopedResourceHost {
+    host;
+    models;
+    constructor(owner, host) {
+        super(owner);
+        this.host = host;
+        this.models = Object.freeze({ get: (name) => this.host.models.get(this.qualify(name)) });
+    }
+    get dialect() {
+        return this.host.dialect;
+    }
+    get started() {
+        return this.host.started;
+    }
+    define(name, definition) {
+        this.host.define(this.qualify(name), definition);
+    }
+    tables() {
+        return Object.freeze(this.host.tables().flatMap((name) => {
+            const logical = this.unqualify(name);
+            return logical === undefined ? [] : [logical];
+        }));
     }
 }
 /**

package/lib/html-renderer.d.ts

@@ -1,10 +1,11 @@
 export interface HtmlRenderOptions {
     readonly width?: number;
+    /** 兼容旧调用方；当前实现传 `svg` 也会降级为 png。 */
     readonly format?: 'png' | 'svg';
     readonly backgroundColor?: string;
 }
 export interface HtmlRenderResult {
-    /** PNG 时为 Buffer/Uint8Array，SVG 时为 string。 */
+    /** 当前实现恒为 png：Buffer/Uint8Array。 */
     readonly data: unknown;
     readonly format: 'png' | 'svg';
     readonly width: number;

package/lib/inbox.d.ts

@@ -5,7 +5,7 @@ import type { DatabaseHost } from './database-host.js';
  * 列结构对齐 packages/im/zhin/src/setup/register-inbox.ts（legacy 读路径 SSOT），
  * request/notice 额外补 consumed/consumed_at 列（对齐 legacy host-api
  * endpoint-persistence 的 console_bot_requests/notices consumed 标记方式），
- * 供 console-rpc-extended 的 endpoint:requestConsumed/noticeConsumed 写路径使用。
+ * 供 console-rpc-extended 的 request.consumed / notice.consumed 写路径使用。
  */
 export declare const INBOX_TABLE_MESSAGE = "unified_inbox_message";
 export declare const INBOX_TABLE_REQUEST = "unified_inbox_request";

package/lib/inbox.js

@@ -5,7 +5,7 @@ import { createToken } from './token.js';
  * 列结构对齐 packages/im/zhin/src/setup/register-inbox.ts（legacy 读路径 SSOT），
  * request/notice 额外补 consumed/consumed_at 列（对齐 legacy host-api
  * endpoint-persistence 的 console_bot_requests/notices consumed 标记方式），
- * 供 console-rpc-extended 的 endpoint:requestConsumed/noticeConsumed 写路径使用。
+ * 供 console-rpc-extended 的 request.consumed / notice.consumed 写路径使用。
  */
 export const INBOX_TABLE_MESSAGE = 'unified_inbox_message';
 export const INBOX_TABLE_REQUEST = 'unified_inbox_request';

package/lib/index.d.ts

@@ -7,10 +7,13 @@ export * from './capability.js';
 export * from './dispose.js';
 export * from './identity.js';
 export { GenerationAdmissionGate, bindGenerationAdmission, createGenerationAdmissionGate, generationAdmissionBinder, generationAdmissionSource, type GenerationAdmissionBindable, type GenerationAdmissionSource, } from './admission.js';
-export * from './generation-store.js';
 export * from './handoff.js';
 /** @public 用户侧创作面：`definePlugin`（`plugin.ts` 约定入口，承诺 semver）。 */
 export * from './plugin.js';
+/** @public Root configuration contract shared by Runtime and composition tooling. */
+export * from './plugin-configuration.js';
+export * from './root-config-file.js';
+export * from './root-config-document.js';
 /** @internal Runtime 内部：RootRuntime / RootController。 */
 export * from './root-controller.js';
 export * from './shared-lifetime.js';

package/lib/index.js

@@ -7,10 +7,13 @@ export * from './capability.js';
 export * from './dispose.js';
 export * from './identity.js';
 export { GenerationAdmissionGate, bindGenerationAdmission, createGenerationAdmissionGate, generationAdmissionBinder, generationAdmissionSource, } from './admission.js';
-export * from './generation-store.js';
 export * from './handoff.js';
 /** @public 用户侧创作面：`definePlugin`（`plugin.ts` 约定入口，承诺 semver）。 */
 export * from './plugin.js';
+/** @public Root configuration contract shared by Runtime and composition tooling. */
+export * from './plugin-configuration.js';
+export * from './root-config-file.js';
+export * from './root-config-document.js';
 /** @internal Runtime 内部：RootRuntime / RootController。 */
 export * from './root-controller.js';
 export * from './shared-lifetime.js';

package/lib/owner-scoped-resource-host.d.ts

@@ -0,0 +1,9 @@
+import { type PluginId } from './identity.js';
+/** Shared owner identity and physical-name invariant for process-wide resources. */
+export declare abstract class OwnerScopedResourceHost {
+    readonly owner: PluginId;
+    constructor(owner: PluginId);
+    protected qualify(name: string): string;
+    protected unqualify(name: string): string | undefined;
+}
+export declare function qualifyOwnedResourceName(owner: PluginId, name: string): string;

package/lib/owner-scoped-resource-host.js

@@ -0,0 +1,27 @@
+import { pluginOwnerResourceKey } from './identity.js';
+const resourcePrefix = '__zhin_plugin__';
+const resourceSeparator = '__';
+/** Shared owner identity and physical-name invariant for process-wide resources. */
+export class OwnerScopedResourceHost {
+    owner;
+    constructor(owner) {
+        this.owner = owner;
+    }
+    qualify(name) {
+        assertLogicalName(name);
+        return qualifyOwnedResourceName(this.owner, name);
+    }
+    unqualify(name) {
+        const prefix = `${resourcePrefix}${pluginOwnerResourceKey(this.owner)}${resourceSeparator}`;
+        return name.startsWith(prefix) ? name.slice(prefix.length) : undefined;
+    }
+}
+export function qualifyOwnedResourceName(owner, name) {
+    assertLogicalName(name);
+    return `${resourcePrefix}${pluginOwnerResourceKey(owner)}${resourceSeparator}${name}`;
+}
+function assertLogicalName(name) {
+    if (!name || name.startsWith(resourcePrefix)) {
+        throw new TypeError(`Invalid plugin resource name: ${name}`);
+    }
+}

package/lib/plugin-configuration.d.ts

@@ -0,0 +1,15 @@
+/** Canonical `zhin.config.*#plugins` shape keyed by Plugin instanceKey. */
+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 {
+    readonly source: string;
+    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.
+ */
+export declare function readPluginConfigurationMap(document: Readonly<Record<string, unknown>>, source?: string): PluginConfigurationMap;

package/lib/plugin-configuration.js

@@ -0,0 +1,26 @@
+const EMPTY_PLUGIN_CONFIGURATION = Object.freeze({});
+/** Raised when a Root config still uses a non-canonical Plugin configuration shape. */
+export class PluginConfigurationShapeError extends TypeError {
+    source;
+    constructor(source = 'Root config') {
+        super(`${source}.plugins must be an object keyed by Plugin instanceKey`);
+        this.source = source;
+        this.name = 'PluginConfigurationShapeError';
+    }
+}
+/**
+ * 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.
+ */
+export function readPluginConfigurationMap(document, source = 'Root config') {
+    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;
+}

package/lib/plugin.d.ts

@@ -56,10 +56,10 @@ export interface PluginDefinition<TConfig = unknown> {
  * });
  * ```
  *
- * Put capabilities in convention files such as `commands/hello.ts`, each with
+ * Put capabilities in convention files such as `commands/hello/index.ts`, each with
  * one default export.
  */
 export declare function definePlugin<TConfig = unknown>(definition: PluginDefinition<TConfig>): Readonly<PluginDefinition<TConfig>>;
-export { databaseHostToken, type DatabaseHostConsole, type DatabaseHostModel, type DatabaseHostSelection, type DatabaseHostSelectResult, type DatabaseHostTable, type DatabaseHostType, type PluginDatabaseHost, } from './database-host.js';
+export { databaseHostToken, type DatabaseHostConsole, type DatabaseHostModel, type DatabaseHostSelection, type DatabaseHostSelectResult, type DatabaseHostTable, type DatabaseHostType, PluginDatabaseHost, } from './database-host.js';
 export { outboundHostToken, type OutboundConversation, type OutboundEditInput, type OutboundEndpointCapabilities, type OutboundEndpointInput, type OutboundEndpointOperation, type OutboundHost, type OutboundMessage, type OutboundReactionInput, type OutboundRecallInput, type OutboundRemoveReactionInput, type OutboundSendInput, type OutboundTypingInput, } from './outbound-host.js';
-export { scheduleHostToken, type PluginScheduleHost, type ScheduleJobRegistration, } from './schedule-host.js';
+export { scheduleHostToken, PluginScheduleHost, type ScheduleJobRegistration, } from './schedule-host.js';

package/lib/plugin.js

@@ -14,7 +14,7 @@ const pluginNamePattern = /^[a-z][a-z0-9-]*$/;
  * });
  * ```
  *
- * Put capabilities in convention files such as `commands/hello.ts`, each with
+ * Put capabilities in convention files such as `commands/hello/index.ts`, each with
  * one default export.
  */
 export function definePlugin(definition) {
@@ -28,6 +28,6 @@ export function definePlugin(definition) {
     });
 }
 // The application facade exposes these Host contracts beside definePlugin.
-export { databaseHostToken, } from './database-host.js';
+export { databaseHostToken, PluginDatabaseHost, } from './database-host.js';
 export { outboundHostToken, } from './outbound-host.js';
-export { scheduleHostToken, } from './schedule-host.js';
+export { scheduleHostToken, PluginScheduleHost, } from './schedule-host.js';

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

@@ -0,0 +1,33 @@
+export type RuntimeConfigDocument = Readonly<Record<string, unknown>>;
+export type ConfigPatch = {
+    readonly op: 'set';
+    readonly path: readonly string[];
+    readonly value: unknown;
+} | {
+    readonly op: 'remove';
+    readonly path: readonly string[];
+};
+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 {
+    /** Files whose external edits invalidate this document snapshot. */
+    readonly sources?: readonly string[];
+    read(): Promise<ConfigDocumentSnapshot>;
+    prepare(current: ConfigDocumentSnapshot, patches: readonly ConfigPatch[]): Promise<PreparedConfigDocument>;
+}
+export declare class ConfigDocumentDivergenceError extends Error {
+    constructor();
+}
+export declare class ConfigPatchPathError extends Error {
+    constructor(message: string);
+}
+/** Applies structural patches without mutating the source document. */
+export declare function applyConfigPatches(document: RuntimeConfigDocument, patches: readonly ConfigPatch[]): RuntimeConfigDocument;

package/lib/root-config-document.js

@@ -0,0 +1,116 @@
+export class ConfigDocumentDivergenceError extends Error {
+    constructor() {
+        super('ConfigDocument adapter candidate differs from the validated Runtime candidate');
+        this.name = 'ConfigDocumentDivergenceError';
+    }
+}
+export class ConfigPatchPathError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'ConfigPatchPathError';
+    }
+}
+/** Applies structural patches without mutating the source document. */
+export function applyConfigPatches(document, patches) {
+    let candidate = structuredClone(document);
+    for (const patch of patches)
+        candidate = applyConfigPatch(candidate, patch);
+    return Object.freeze(candidate);
+}
+function applyConfigPatch(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 = readChild(target, segment, path.slice(0, index + 1));
+        if (existing === undefined) {
+            const created = {};
+            target[segment] = created;
+            target = created;
+        }
+        else {
+            target = requireContainer(existing, path.slice(0, index + 1));
+        }
+    }
+    writeChild(target, lastSegment(path), value, path);
+}
+function removeValue(document, path) {
+    let target = document;
+    for (const [index, segment] of path.slice(0, -1).entries()) {
+        const existing = readChild(target, segment, path.slice(0, index + 1));
+        if (existing === undefined)
+            return;
+        target = requireContainer(existing, path.slice(0, index + 1));
+    }
+    const segment = lastSegment(path);
+    if (Array.isArray(target)) {
+        target.splice(arrayIndex(segment, target, path), 1);
+        return;
+    }
+    delete target[segment];
+}
+function cloneDocument(value) {
+    const document = structuredClone(value);
+    if (!document || typeof document !== 'object' || Array.isArray(document)) {
+        throw new ConfigPatchPathError('The config document root must be an object');
+    }
+    return document;
+}
+function readChild(container, segment, path) {
+    if (Array.isArray(container))
+        return container[arrayIndex(segment, container, path)];
+    return container[segment];
+}
+function writeChild(container, segment, value, path) {
+    if (Array.isArray(container)) {
+        container[arrayIndex(segment, container, path)] = value;
+        return;
+    }
+    container[segment] = value;
+}
+function arrayIndex(segment, container, path) {
+    if (!/^(0|[1-9]\d*)$/.test(segment)) {
+        throw new ConfigPatchPathError(`Config path ${pointer(path)} requires an array index, got "${segment}"`);
+    }
+    const index = Number(segment);
+    if (index >= container.length) {
+        throw new ConfigPatchPathError(`Config path ${pointer(path)} is out of bounds (array length ${container.length})`);
+    }
+    return index;
+}
+function requireContainer(value, path) {
+    if (!value || typeof value !== 'object') {
+        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('/')}`;
+}

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

@@ -0,0 +1,9 @@
+export declare const ROOT_CONFIG_FILE_NAMES: readonly ["config.yml", "config.yaml", "config.json", "zhin.config.yml", "zhin.config.yaml", "zhin.config.json"];
+export type RootConfigFileName = typeof ROOT_CONFIG_FILE_NAMES[number];
+export type RootConfigFormat = 'yaml' | 'json';
+/** File materialized when a project has no Root configuration yet. */
+export declare const DEFAULT_ROOT_CONFIG_FILE_NAME: RootConfigFileName;
+/** Returns the only configuration formats accepted by Root Runtime. */
+export declare function rootConfigFormat(filePath: string): RootConfigFormat | undefined;
+/** Enforces a single Root configuration authority for one project. */
+export declare function selectRootConfigFile(existingFiles: readonly string[]): string | undefined;

package/lib/root-config-file.js

@@ -0,0 +1,29 @@
+export const ROOT_CONFIG_FILE_NAMES = Object.freeze([
+    'config.yml',
+    'config.yaml',
+    'config.json',
+    'zhin.config.yml',
+    'zhin.config.yaml',
+    'zhin.config.json',
+]);
+/** File materialized when a project has no Root configuration yet. */
+export const DEFAULT_ROOT_CONFIG_FILE_NAME = 'zhin.config.yml';
+/** Returns the only configuration formats accepted by Root Runtime. */
+export function rootConfigFormat(filePath) {
+    const fileName = filePath.split(/[\\/]/u).pop();
+    if (!fileName || !ROOT_CONFIG_FILE_NAMES.includes(fileName))
+        return undefined;
+    const extension = /\.[^.]+$/u.exec(fileName)?.[0];
+    if (extension === '.yml' || extension === '.yaml')
+        return 'yaml';
+    if (extension === '.json')
+        return 'json';
+    return undefined;
+}
+/** Enforces a single Root configuration authority for one project. */
+export function selectRootConfigFile(existingFiles) {
+    if (existingFiles.length > 1) {
+        throw new Error(`Multiple Root config files found: ${existingFiles.join(', ')}`);
+    }
+    return existingFiles[0];
+}

package/lib/schedule-host.d.ts

@@ -1,4 +1,5 @@
-import { type PluginId } from './identity.js';
+import type { PluginId } from './identity.js';
+import { OwnerScopedResourceHost } from './owner-scoped-resource-host.js';
 /**
  * Thin Host Resource for Plugin Runtime cron jobs.
  * Implementations typically wrap `@zhin.js/schedule` CalendarScheduler (solar cron).
@@ -23,8 +24,10 @@ export interface ScheduleHost {
     }[];
 }
 /** Scoped scheduling surface exposed to a Plugin setup function. */
-export interface PluginScheduleHost {
-    readonly owner: PluginId;
+export declare function qualifyPluginScheduleId(owner: PluginId, id: string): string;
+export declare class PluginScheduleHost extends OwnerScopedResourceHost {
+    private readonly host;
+    constructor(owner: PluginId, host: ScheduleHost);
     register(job: ScheduleJobRegistration): () => void;
     list(): readonly {
         readonly id: string;
@@ -32,11 +35,6 @@ export interface PluginScheduleHost {
         readonly description?: string;
     }[];
 }
-export declare function qualifyPluginScheduleId(owner: PluginId, id: string): string;
-export declare function unqualifyPluginScheduleId(owner: PluginId, id: string): string | undefined;
-export declare function createPluginScheduleHost(owner: PluginId, host: ScheduleHost): PluginScheduleHost;
-/** See unwrapPluginDatabaseHost: preserves legacy custom RootResource installers. */
-export declare function unwrapPluginScheduleHost(host: ScheduleHost | PluginScheduleHost): ScheduleHost;
 /** @public Plugin-facing token; Runtime injects a facade bound to the current owner. */
 export declare const scheduleHostToken: import("./token.js").Token<PluginScheduleHost>;
 /** Root-only process scheduler for CLI composition and Console administration. */

package/lib/schedule-host.js

@@ -1,49 +1,29 @@
-import { pluginOwnerResourceKey, rootPluginId } from './identity.js';
+import { OwnerScopedResourceHost, qualifyOwnedResourceName, } from './owner-scoped-resource-host.js';
 import { createToken } from './token.js';
-const jobPrefix = '__zhin_plugin__';
-const jobSeparator = '__';
-const roots = new WeakMap();
+/** Scoped scheduling surface exposed to a Plugin setup function. */
 export function qualifyPluginScheduleId(owner, id) {
-    assertLogicalJobId(id);
-    if (owner === rootPluginId())
-        return id;
-    return `${jobPrefix}${pluginOwnerResourceKey(owner)}${jobSeparator}${id}`;
+    return qualifyOwnedResourceName(owner, id);
 }
-export function unqualifyPluginScheduleId(owner, id) {
-    if (owner === rootPluginId())
-        return id.startsWith(jobPrefix) ? undefined : id;
-    const prefix = `${jobPrefix}${pluginOwnerResourceKey(owner)}${jobSeparator}`;
-    return id.startsWith(prefix) ? id.slice(prefix.length) : undefined;
-}
-export function createPluginScheduleHost(owner, host) {
-    const facade = Object.freeze({
-        owner,
-        register(job) {
-            return host.register({ ...job, id: qualifyPluginScheduleId(owner, job.id), owner });
-        },
-        list() {
-            return Object.freeze(host.list().flatMap((job) => {
-                const id = unqualifyPluginScheduleId(owner, job.id);
-                if (id === undefined)
-                    return [];
-                return [Object.freeze({
-                        id,
-                        cron: job.cron,
-                        ...(job.description === undefined ? {} : { description: job.description }),
-                    })];
-            }));
-        },
-    });
-    roots.set(facade, host);
-    return facade;
-}
-/** See unwrapPluginDatabaseHost: preserves legacy custom RootResource installers. */
-export function unwrapPluginScheduleHost(host) {
-    return roots.get(host) ?? host;
-}
-function assertLogicalJobId(id) {
-    if (!id || id.startsWith(jobPrefix)) {
-        throw new TypeError(`Invalid plugin schedule id: ${id}`);
+export class PluginScheduleHost extends OwnerScopedResourceHost {
+    host;
+    constructor(owner, host) {
+        super(owner);
+        this.host = host;
+    }
+    register(job) {
+        return this.host.register({ ...job, id: this.qualify(job.id), owner: this.owner });
+    }
+    list() {
+        return Object.freeze(this.host.list().flatMap((job) => {
+            const id = this.unqualify(job.id);
+            if (id === undefined)
+                return [];
+            return [Object.freeze({
+                    id,
+                    cron: job.cron,
+                    ...(job.description === undefined ? {} : { description: job.description }),
+                })];
+        }));
     }
 }
 /** @public Plugin-facing token; Runtime injects a facade bound to the current owner. */

package/lib/system-log.d.ts

@@ -2,8 +2,7 @@ import type { DatabaseHost } from './database-host.js';
 /**
  * 系统日志表（console logs 页数据源）定义与写入辅助。
  *
- * 列结构对齐 packages/im/core/src/models/system-log.ts（legacy SystemLogDefinition，
- * 读取端为 packages/host/http console-rest-pages registerLogsRoutes）。
+ * 读取端为 packages/host/http console-rest-pages registerLogsRoutes。
  */
 export declare const SYSTEM_LOG_TABLE = "SystemLog";
 export declare const SYSTEM_LOG_DEFINITION: Record<string, unknown>;

package/lib/system-log.js

@@ -1,8 +1,7 @@
 /**
  * 系统日志表（console logs 页数据源）定义与写入辅助。
  *
- * 列结构对齐 packages/im/core/src/models/system-log.ts（legacy SystemLogDefinition，
- * 读取端为 packages/host/http console-rest-pages registerLogsRoutes）。
+ * 读取端为 packages/host/http console-rest-pages registerLogsRoutes。
  */
 export const SYSTEM_LOG_TABLE = 'SystemLog';
 export const SYSTEM_LOG_DEFINITION = {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhin.js/plugin-runtime",
-  "version": "1.1.8",
+  "version": "1.1.10",
   "description": "Zero-dependency Plugin tree, Scope and atomic generation runtime for Zhin",
   "type": "module",
   "main": "./lib/index.js",

package/lib/generation-store.d.ts

@@ -1,32 +0,0 @@
-import { DisposeStack, type Dispose } from './dispose.js';
-/**
- * Minimal structural view of a plugin setup context: anything owning a
- * generation-scoped lifecycle (e.g. PluginSetupContext) can provide values.
- */
-export interface GenerationStoreContext {
-    readonly lifecycle: DisposeStack;
-}
-export interface GenerationStore<T> {
-    /**
-     * Publish `value` as the current generation's value. The registration is
-     * removed automatically when `context.lifecycle` disposes (generation end);
-     * the returned Dispose unregisters manually and is idempotent.
-     */
-    provide(context: GenerationStoreContext, value: T): Dispose;
-    /** Latest live value; throws a store-named error when none was provided. */
-    use(): T;
-    /** Latest live value, or `undefined` when none was provided. */
-    tryUse(): T | undefined;
-    /** Drop every registration across all generations. Mainly for tests. */
-    clear(): void;
-}
-/**
- * Generation-scoped replacement for module-level `let _x` singletons.
- *
- * Provided values form a stack: the newest live registration wins, and when a
- * generation ends its registration is removed via `context.lifecycle`,
- * re-exposing the previous generation's value. This structurally prevents
- * stale references to an already disposed generation (the repeater singleton
- * / rss `_db` class of bugs).
- */
-export declare function createGenerationStore<T>(name: string): GenerationStore<T>;

package/lib/generation-store.js

@@ -1,38 +0,0 @@
-/**
- * Generation-scoped replacement for module-level `let _x` singletons.
- *
- * Provided values form a stack: the newest live registration wins, and when a
- * generation ends its registration is removed via `context.lifecycle`,
- * re-exposing the previous generation's value. This structurally prevents
- * stale references to an already disposed generation (the repeater singleton
- * / rss `_db` class of bugs).
- */
-export function createGenerationStore(name) {
-    const registrations = [];
-    const unregister = (registration) => {
-        const index = registrations.lastIndexOf(registration);
-        if (index >= 0)
-            registrations.splice(index, 1);
-    };
-    return {
-        provide(context, value) {
-            const registration = Object.freeze({ value });
-            registrations.push(registration);
-            context.lifecycle.add(() => unregister(registration));
-            return () => unregister(registration);
-        },
-        use() {
-            const latest = registrations[registrations.length - 1];
-            if (!latest) {
-                throw new Error(`Generation store "${name}" has no live value — call provide(context, value) during plugin setup`);
-            }
-            return latest.value;
-        },
-        tryUse() {
-            return registrations[registrations.length - 1]?.value;
-        },
-        clear() {
-            registrations.length = 0;
-        },
-    };
-}