@zhin.js/plugin-runtime 1.1.15 → 1.1.17

package/lib/database-host.d.ts

@@ -35,11 +35,20 @@ export interface DatabaseHostModel {
      */
     count?(where?: Record<string, unknown>): Promise<number>;
 }
+/** Callback-scoped transaction models; no raw SQL or administration access. */
+export interface DatabaseHostTransaction {
+    model(name: string): DatabaseHostModel;
+}
 export type DatabaseHostType = 'related' | 'document' | 'keyvalue';
 export interface DatabaseHostTable {
     readonly name: string;
     readonly columns?: Readonly<Record<string, unknown>>;
 }
+/** Explicit, additive upgrades applied before SQL models become available. */
+export interface DatabaseTableOptions {
+    /** Names from this table's definition. Existing columns and data remain untouched. */
+    readonly addColumns?: readonly string[];
+}
 export interface DatabaseHostSelectResult {
     readonly rows: readonly unknown[];
     readonly total: number;
@@ -79,12 +88,14 @@ 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;
+    define(name: string, definition: Record<string, unknown>, options?: DatabaseTableOptions): void;
     /** Names of tables registered via `define` (Console `db:tables`). */
     tables(): readonly string[];
     models: {
         get(name: string): DatabaseHostModel | undefined;
     };
+    /** Atomic SQL operations. The callback must await all operations before returning. */
+    transaction?<T>(callback: (transaction: DatabaseHostTransaction) => Promise<T>): Promise<T>;
     /** Root-only management port; absent on lightweight test/memory hosts. */
     readonly console?: DatabaseHostConsole;
     /**
@@ -123,9 +134,12 @@ export declare class PluginDatabaseHost extends OwnerScopedResourceHost {
     get [generationAdmissionSource](): readonly GenerationAdmissionGate[];
     get dialect(): string;
     get started(): boolean;
-    define(name: string, definition: Record<string, unknown>): void;
+    define(name: string, definition: Record<string, unknown>, options?: DatabaseTableOptions): void;
     tables(): readonly string[];
+    transaction<T>(callback: (transaction: DatabaseHostTransaction) => Promise<T>): Promise<T>;
 }
+/** A saved query/model cannot escape the callback and reuse the transaction. */
+export declare function guardTransactionModel(model: DatabaseHostModel, check: () => void): DatabaseHostModel;
 /**
  * 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

@@ -54,8 +54,10 @@ export class PluginDatabaseHost extends OwnerScopedResourceHost {
     get started() {
         return this.#host.started;
     }
-    define(name, definition) {
-        this.#operation.setup(() => this.#host.define(this.qualify(name), definition));
+    define(name, definition, options) {
+        this.#operation.setup(() => options === undefined
+            ? this.#host.define(this.qualify(name), definition)
+            : this.#host.define(this.qualify(name), definition, options));
     }
     tables() {
         return this.#operation.setup(() => Object.freeze(this.#host.tables().flatMap((name) => {
@@ -63,6 +65,27 @@ export class PluginDatabaseHost extends OwnerScopedResourceHost {
             return logical === undefined ? [] : [logical];
         })));
     }
+    async transaction(callback) {
+        if (!this.#host.transaction)
+            throw new Error('Database Host does not support transactions');
+        return this.#execute(() => this.#host.transaction(async (transaction) => {
+            let active = true;
+            const requireActive = () => { if (!active)
+                throw new Error('Database transaction is already closed'); };
+            try {
+                return await callback(Object.freeze({ model: (name) => {
+                        requireActive();
+                        // Reuse the ordinary facade so qualification and generation checks stay identical.
+                        const model = transaction.model(this.qualify(name));
+                        const guarded = guardTransactionModel(model, requireActive);
+                        return this.#bindModel(guarded);
+                    } }));
+            }
+            finally {
+                active = false;
+            }
+        }));
+    }
     #bindSelection(selection) {
         const modify = (operation) => this.#operation.setup(() => {
             const next = operation();
@@ -94,6 +117,21 @@ export class PluginDatabaseHost extends OwnerScopedResourceHost {
         return this.#operation.run(operation);
     }
 }
+/** A saved query/model cannot escape the callback and reuse the transaction. */
+export function guardTransactionModel(model, check) {
+    const selection = (source) => ({
+        where(query) { check(); return selection(source.where(query)); },
+        orderBy(field, direction) { check(); return selection(source.orderBy(field, direction)); },
+        limit(count) { check(); return selection(source.limit(count)); },
+        then(resolve, reject) { return Promise.resolve().then(() => { check(); return source; }).then(resolve, reject); },
+    });
+    return {
+        select: (...fields) => { check(); return selection(model.select(...fields)); },
+        insert: async (row) => { check(); return model.insert(row); },
+        update: patch => { check(); return { where: async (query) => { check(); return model.update(patch).where(query); } }; },
+        delete: () => { check(); return { where: async (query) => { check(); return model.delete().where(query); } }; },
+    };
+}
 /**
  * Plugin-facing scoped persistence token. Runtime replaces this binding for
  * every Plugin Scope; plugin code must never receive the process-wide host.

package/lib/i18n.d.ts

@@ -0,0 +1,24 @@
+import type { DeliveryTarget } from './delivery-target.js';
+/** Supported display languages. Time zone and command identities are independent. */
+export type Locale = 'zh-CN' | 'en';
+export declare const DEFAULT_LOCALE: Locale;
+export declare const SUPPORTED_LOCALES: readonly ["zh-CN", "en"];
+export declare function isLocale(value: unknown): value is Locale;
+/** Resolve an absent display preference; configuration writes validate with isLocale. */
+export declare function resolveLocale(value: unknown): Locale;
+/** Immutable project language, projected with the operation's generation. */
+export declare const projectLocaleToken: import("./token.js").Token<Locale>;
+/** Root-owned preferences; identity never comes from display names or profile text. */
+export interface UserLocalePreferences {
+    get(endpoint: DeliveryTarget['endpoint'], senderId: string): Promise<Locale | undefined>;
+    set(endpoint: DeliveryTarget['endpoint'], senderId: string, locale: Locale): Promise<void>;
+}
+export declare const userLocalePreferencesToken: import("./token.js").Token<UserLocalePreferences>;
+export type MessageCatalog = Readonly<Record<string, Readonly<Record<Locale, string>>>>;
+export type MessageValues = Readonly<Record<string, string | number>>;
+/**
+ * A package-owned, complete bilingual catalog. No global language or registration.
+ * Placeholder substitution is one pass: user text cannot become another template.
+ * Values remain plain text; HTML/JSX escaping belongs to the existing renderer.
+ */
+export declare function createMessages<const T extends MessageCatalog>(catalog: T): (locale: Locale | undefined, key: keyof T & string, values?: MessageValues) => string;

package/lib/i18n.js

@@ -0,0 +1,38 @@
+import { createToken } from './token.js';
+export const DEFAULT_LOCALE = 'zh-CN';
+export const SUPPORTED_LOCALES = Object.freeze(['zh-CN', 'en']);
+export function isLocale(value) {
+    return value === 'zh-CN' || value === 'en';
+}
+/** Resolve an absent display preference; configuration writes validate with isLocale. */
+export function resolveLocale(value) {
+    return isLocale(value) ? value : DEFAULT_LOCALE;
+}
+/** Immutable project language, projected with the operation's generation. */
+export const projectLocaleToken = createToken('zhin.project-locale');
+export const userLocalePreferencesToken = createToken('zhin.user-locale-preferences');
+/**
+ * A package-owned, complete bilingual catalog. No global language or registration.
+ * Placeholder substitution is one pass: user text cannot become another template.
+ * Values remain plain text; HTML/JSX escaping belongs to the existing renderer.
+ */
+export function createMessages(catalog) {
+    const entries = Object.freeze(Object.fromEntries(Object.entries(catalog).map(([key, value]) => {
+        const keys = (text) => [...new Set([...text.matchAll(/\{([a-zA-Z][\w]*)\}/gu)].map(match => match[1]))].sort();
+        if (typeof value['zh-CN'] !== 'string' || typeof value.en !== 'string'
+            || JSON.stringify(keys(value['zh-CN'])) !== JSON.stringify(keys(value.en))) {
+            throw new TypeError(`Invalid bilingual message catalog entry: ${key}`);
+        }
+        return [key, Object.freeze({ ...value })];
+    })));
+    return (locale, key, values = {}) => {
+        const entry = entries[key];
+        if (!Object.hasOwn(entries, key) || !entry)
+            throw new TypeError(`Unknown message catalog entry: ${key}`);
+        return entry[resolveLocale(locale)].replace(/\{([a-zA-Z][\w]*)\}/gu, (_match, name) => {
+            if (!Object.hasOwn(values, name))
+                throw new TypeError(`Missing message value: ${name}`);
+            return String(values[name]);
+        });
+    };
+}

package/lib/inbox.d.ts

@@ -10,6 +10,28 @@ import type { DatabaseHost } from './database-host.js';
 export declare const INBOX_TABLE_MESSAGE = "unified_inbox_message";
 export declare const INBOX_TABLE_REQUEST = "unified_inbox_request";
 export declare const INBOX_TABLE_NOTICE = "unified_inbox_notice";
+export declare const INBOX_MESSAGE_QUERY_COLUMNS: {
+    readonly direction: {
+        readonly type: "text";
+        readonly nullable: true;
+    };
+    readonly endpoint_capability_id: {
+        readonly type: "text";
+        readonly nullable: true;
+    };
+    readonly endpoint_adapter_id: {
+        readonly type: "text";
+        readonly nullable: true;
+    };
+    readonly thread_id: {
+        readonly type: "text";
+        readonly nullable: true;
+    };
+    readonly query_version: {
+        readonly type: "integer";
+        readonly nullable: true;
+    };
+};
 export declare const INBOX_MESSAGE_DEFINITION: Record<string, unknown>;
 export declare const INBOX_REQUEST_DEFINITION: Record<string, unknown>;
 export declare const INBOX_NOTICE_DEFINITION: Record<string, unknown>;

package/lib/inbox.js

@@ -10,7 +10,15 @@ import { createToken } from './token.js';
 export const INBOX_TABLE_MESSAGE = 'unified_inbox_message';
 export const INBOX_TABLE_REQUEST = 'unified_inbox_request';
 export const INBOX_TABLE_NOTICE = 'unified_inbox_notice';
+export const INBOX_MESSAGE_QUERY_COLUMNS = {
+    direction: { type: 'text', nullable: true },
+    endpoint_capability_id: { type: 'text', nullable: true },
+    endpoint_adapter_id: { type: 'text', nullable: true },
+    thread_id: { type: 'text', nullable: true },
+    query_version: { type: 'integer', nullable: true },
+};
 export const INBOX_MESSAGE_DEFINITION = {
+    ...INBOX_MESSAGE_QUERY_COLUMNS,
     id: { type: 'integer', primary: true, autoIncrement: true },
     adapter: { type: 'text', nullable: false },
     endpoint_id: { type: 'text', nullable: false },

package/lib/index.d.ts

@@ -12,6 +12,7 @@ export * from './handoff.js';
 export * from './plugin.js';
 /** @public Root configuration contract shared by Runtime and composition tooling. */
 export * from './plugin-configuration.js';
+export * from './i18n.js';
 export * from './root-config-file.js';
 export * from './root-config-document.js';
 /** @internal Runtime 内部：RootRuntime / RootController。 */
@@ -33,7 +34,10 @@ export * from './outbound-host.js';
 export * from './outbound-sender.js';
 export * from './delivery-target.js';
 export * from './persistent-state.js';
+export * from './relational-state.js';
 export * from './inbox.js';
 export * from './system-log.js';
 export * from './plugin-verification.js';
 export * from './plugin-tasks.js';
+export * from './task-storage.js';
+export * from './plugin-console-rpc.js';

package/lib/index.js

@@ -12,6 +12,7 @@ export * from './handoff.js';
 export * from './plugin.js';
 /** @public Root configuration contract shared by Runtime and composition tooling. */
 export * from './plugin-configuration.js';
+export * from './i18n.js';
 export * from './root-config-file.js';
 export * from './root-config-document.js';
 /** @internal Runtime 内部：RootRuntime / RootController。 */
@@ -33,7 +34,10 @@ export * from './outbound-host.js';
 export * from './outbound-sender.js';
 export * from './delivery-target.js';
 export * from './persistent-state.js';
+export * from './relational-state.js';
 export * from './inbox.js';
 export * from './system-log.js';
 export * from './plugin-verification.js';
 export * from './plugin-tasks.js';
+export * from './task-storage.js';
+export * from './plugin-console-rpc.js';

package/lib/outbound-host.d.ts

@@ -1,5 +1,6 @@
 import type { DeliveryTarget } from './delivery-target.js';
 import type { PluginId } from './identity.js';
+import type { Locale } from './i18n.js';
 import { generationAdmissionBinder, generationAdmissionSource, type GenerationAdmissionGate } from './admission.js';
 /**
  * 未锚定 endpoint 的会话地址（结构对齐 `@zhin.js/im-contract` 的
@@ -21,6 +22,8 @@ export interface OutboundConversation {
  * `sendEndpointMessage` (resolve adapter/endpoint → AdapterIndex.send).
  */
 export interface OutboundSendInput {
+    /** Language captured by the originating operation or persisted task. */
+    readonly locale?: Locale;
     readonly adapter: string;
     readonly endpointKey: string;
     readonly conversation: OutboundConversation;
@@ -73,7 +76,9 @@ export interface OutboundMessage {
 }
 export interface OutboundHost {
     /** Sends to persisted exact identities, rejecting stale addresses instead of aliasing another bot. */
-    sendTarget?(target: DeliveryTarget, content: unknown): Promise<string | null>;
+    sendTarget?(target: DeliveryTarget, content: unknown, options?: Readonly<{
+        locale?: Locale;
+    }>): Promise<string | null>;
     /** Runs related operations against one IM Runtime snapshot captured at ingress. */
     runWithView?<T>(operation: () => Promise<T>): Promise<T>;
     /** Exact operations declared by one live Endpoint. */
@@ -95,7 +100,9 @@ export interface OutboundHost {
 }
 /** Root-only process port: requester is supplied by the owner-bound facade. */
 export interface OutboundRootHost extends Omit<OutboundHost, 'sendTarget'> {
-    sendTarget?(target: DeliveryTarget, content: unknown, requester: PluginId): Promise<string | null>;
+    sendTarget?(target: DeliveryTarget, content: unknown, requester: PluginId, options?: Readonly<{
+        locale?: Locale;
+    }>): Promise<string | null>;
 }
 /** Preserve the sending plugin as requester, independent of the destination endpoint owner. */
 export declare class PluginOutboundHost implements OutboundHost {

package/lib/outbound-host.js

@@ -28,7 +28,9 @@ export class PluginOutboundHost {
         const recall = host.recall?.bind(host);
         const edit = host.edit?.bind(host);
         const typing = host.typing?.bind(host);
-        this.sendTarget = sendTarget ? async (target, content) => this.#run(() => sendTarget(target, content, this.#owner)) : undefined;
+        this.sendTarget = sendTarget ? async (target, content, options) => this.#run(() => options
+            ? sendTarget(target, content, this.#owner, options)
+            : sendTarget(target, content, this.#owner)) : undefined;
         this.runWithView = runWithView ? (operation) => this.#run(() => runWithView(operation)) : undefined;
         this.capabilities = capabilities ? (input) => this.#run(() => capabilities(input)) : undefined;
         this.addReaction = addReaction ? (input) => this.#run(() => addReaction(input)) : undefined;

package/lib/plugin-console-rpc.d.ts

@@ -0,0 +1,86 @@
+import { type GenerationAdmissionSource } from './admission.js';
+import type { JsonValue } from './persistent-state.js';
+/**
+ * Plugin-registered Console RPC (zhinjs/zhin#970).
+ *
+ * A plugin publishes one {@link PluginConsoleRpc} through {@link pluginConsoleRpcToken}. The Host
+ * exposes it on the existing Console RPC envelope as `plugin.<pluginId>.status` and
+ * `plugin.<pluginId>.<action>`, where `<pluginId>` is the owner PluginId (for example
+ * `root/typesafe`). No WebSocket, no new HTTP route, and no generic config writes.
+ *
+ * Authorization follows the Console Page the method is bound to (`page`): the caller must
+ * satisfy that page's `requiredPermissions` / `requiredRoles`, plus the method's own. The full
+ * (admin) token may call everything. Other tokens (`user` / `demo`) may call a method when they
+ * hold every required permission and role. An action is open to them only when it declares its
+ * own `requiredPermissions` / `requiredRoles` / `anyOfPermissions` (the page's requirements apply on
+ * top, but never grant an action by themselves); an unguarded `status` needs `demo: true`.
+ * `anyOfPermissions` is satisfied by holding at least one of the listed permissions (for a new
+ * permission that coexists with an older one, e.g. `ops:approve` beside `tool_approvals:resolve`).
+ */
+export type PluginConsoleRpcJson = JsonValue;
+export type PluginConsoleRpcInput = Readonly<Record<string, JsonValue>>;
+export interface PluginConsoleRpcCall {
+    /** Aborted when the Host request times out. Long work must observe it. */
+    readonly signal: AbortSignal;
+}
+export interface PluginConsoleRpcMethod<TInput = PluginConsoleRpcInput> {
+    /** Local name of a Page owned by the same plugin (`pages/<page>/index.tsx`). Its access rules apply. */
+    readonly page?: string;
+    /** Extra permissions on top of the page's own requirements. */
+    readonly requiredPermissions?: readonly string[];
+    /** Extra roles on top of the page's own requirements. */
+    readonly requiredRoles?: readonly string[];
+    /**
+     * The caller must also hold at least one of these (in addition to every `requiredPermissions`).
+     * Counts as the method's own requirement for actions.
+     */
+    readonly anyOfPermissions?: readonly string[];
+    /**
+     * Return a small, user-facing JSON shape. Never return raw log records, prompts, chat lines,
+     * secrets or exception text: the Console shows this to ordinary users.
+     */
+    handler(input: TInput, call: PluginConsoleRpcCall): JsonValue | Promise<JsonValue>;
+}
+export interface PluginConsoleRpcStatus extends PluginConsoleRpcMethod<PluginConsoleRpcInput> {
+    /** Allow the demo-scope Console token to read this status. Default `false`. */
+    readonly demo?: boolean;
+}
+export interface PluginConsoleRpcDefinition {
+    /** Read-only status for the plugin's Console page(s): `plugin.<pluginId>.status`. */
+    readonly status?: PluginConsoleRpcStatus;
+    /**
+     * Extra read-only views beside `status`: `plugin.<pluginId>.<name>`. Same access rules as
+     * `status`; use them when one plugin backs several pages with different permissions.
+     */
+    readonly queries?: Readonly<Record<string, PluginConsoleRpcStatus>>;
+    /**
+     * Limited, named actions: `plugin.<pluginId>.<name>`. Non-admin tokens may run one only when the
+     * action declares its own requirements and the token holds them (plus the page's); otherwise
+     * admin-only.
+     */
+    readonly actions?: Readonly<Record<string, PluginConsoleRpcMethod>>;
+}
+export interface NormalizedPluginConsoleRpcMethod {
+    readonly page?: string;
+    readonly requiredPermissions: readonly string[];
+    readonly requiredRoles: readonly string[];
+    /** Empty when the method has no either-of requirement. */
+    readonly anyOfPermissions: readonly string[];
+    readonly demo: boolean;
+    /** `status` and `queries` are read-only; actions are not. */
+    readonly readOnly: boolean;
+    readonly handler: PluginConsoleRpcMethod['handler'];
+}
+/** Value published under {@link pluginConsoleRpcToken}; create it with {@link definePluginConsoleRpc}. */
+export interface PluginConsoleRpc extends GenerationAdmissionSource {
+    readonly methods: ReadonlyMap<string, NormalizedPluginConsoleRpcMethod>;
+}
+/** Safe, user-facing failure. `message` is shown in the Console; never put raw errors in it. */
+export declare class PluginConsoleRpcError extends Error {
+    readonly code: 'invalid_input' | 'conflict' | 'not_found' | 'unsupported' | 'unavailable';
+    constructor(code: PluginConsoleRpcError['code'], message: string);
+}
+export declare const pluginConsoleRpcToken: import("./token.js").Token<PluginConsoleRpc>;
+export declare const PLUGIN_CONSOLE_RPC_STATUS = "status";
+/** Validates and freezes a plugin's Console RPC surface. Throws on invalid names at setup time. */
+export declare function definePluginConsoleRpc(definition: PluginConsoleRpcDefinition): PluginConsoleRpc;

package/lib/plugin-console-rpc.js

@@ -0,0 +1,69 @@
+import { createGenerationAdmissionGate, generationAdmissionSource, } from './admission.js';
+import { createToken } from './token.js';
+/** Safe, user-facing failure. `message` is shown in the Console; never put raw errors in it. */
+export class PluginConsoleRpcError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = 'PluginConsoleRpcError';
+        this.code = code;
+    }
+}
+export const pluginConsoleRpcToken = createToken('zhin.plugin-console-rpc', 'Plugin-owned Console status and limited actions, called through the authenticated Console RPC envelope');
+export const PLUGIN_CONSOLE_RPC_STATUS = 'status';
+const methodNamePattern = /^[a-z][a-z0-9-]{0,63}$/u;
+const pageNamePattern = /^[a-z0-9][a-z0-9-]*$/u;
+/** Validates and freezes a plugin's Console RPC surface. Throws on invalid names at setup time. */
+export function definePluginConsoleRpc(definition) {
+    if (!definition || typeof definition !== 'object')
+        throw new TypeError('Plugin Console RPC definition must be an object');
+    const methods = new Map();
+    if (definition.status !== undefined) {
+        methods.set(PLUGIN_CONSOLE_RPC_STATUS, normalizeMethod('status', definition.status, definition.status.demo === true, true));
+    }
+    for (const [kind, entries] of [['query', definition.queries], ['action', definition.actions]]) {
+        for (const [name, method] of Object.entries(entries ?? {})) {
+            if (!methodNamePattern.test(name))
+                throw new TypeError(`Invalid plugin Console RPC ${kind} name: ${name}`);
+            if (name === PLUGIN_CONSOLE_RPC_STATUS)
+                throw new TypeError('"status" is reserved; declare it as definition.status');
+            if (methods.has(name))
+                throw new TypeError(`Duplicate plugin Console RPC method: ${name}`);
+            const readOnly = kind === 'query';
+            methods.set(name, normalizeMethod(name, method, readOnly && method.demo === true, readOnly));
+        }
+    }
+    if (methods.size === 0)
+        throw new TypeError('Plugin Console RPC must declare status or at least one action');
+    const gate = createGenerationAdmissionGate();
+    const gates = Object.freeze([gate]);
+    return Object.freeze({
+        methods: methods,
+        get [generationAdmissionSource]() { return gates; },
+    });
+}
+function normalizeMethod(name, method, demo, readOnly) {
+    if (!method || typeof method.handler !== 'function') {
+        throw new TypeError(`Plugin Console RPC ${name} must have a handler`);
+    }
+    if (method.page !== undefined && (typeof method.page !== 'string' || !pageNamePattern.test(method.page))) {
+        throw new TypeError(`Plugin Console RPC ${name} has an invalid page name`);
+    }
+    return Object.freeze({
+        ...(method.page === undefined ? {} : { page: method.page }),
+        requiredPermissions: stringList(method.requiredPermissions, `${name} requiredPermissions`),
+        requiredRoles: stringList(method.requiredRoles, `${name} requiredRoles`),
+        anyOfPermissions: stringList(method.anyOfPermissions, `${name} anyOfPermissions`),
+        demo,
+        readOnly,
+        handler: method.handler,
+    });
+}
+function stringList(value, label) {
+    if (value === undefined)
+        return Object.freeze([]);
+    if (!Array.isArray(value) || !value.every((item) => typeof item === 'string' && item.trim())) {
+        throw new TypeError(`Plugin Console RPC ${label} must be non-empty strings`);
+    }
+    return Object.freeze([...new Set(value)].sort());
+}

package/lib/plugin-tasks.d.ts

@@ -1,6 +1,7 @@
 import type { DeliveryTarget } from './delivery-target.js';
 import type { JsonValue } from './persistent-state.js';
 import type { GenerationAdmissionSource } from './admission.js';
+import type { Locale } from './i18n.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. */
@@ -31,19 +32,28 @@ export interface PluginTaskMutationReceipt {
     readonly operation: 'create' | PluginTaskAction;
 }
 export interface PluginTaskMutation {
+    /** Display language only; excluded from mutation identity and notification settings. */
+    readonly locale?: Locale;
     /** 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 i18n?: Readonly<Partial<Record<Locale, Readonly<{
+        title?: string;
+        description?: string;
+        effects?: readonly string[];
+    }>>>>;
     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>;
+    read(options?: Readonly<{
+        locale?: Locale;
+    }>): Promise<PluginTaskSnapshot>;
     create(input: PluginTaskMutation & Readonly<{
         target: DeliveryTarget;
         parameters: Readonly<Record<string, JsonValue>>;

package/lib/plugin-verification.d.ts

@@ -1,14 +1,19 @@
+import type { Locale } from './i18n.js';
 /** A deliberate business check. Effects must describe every write or external action. */
 export interface PluginVerificationCheck {
     readonly id: string;
     readonly title: string;
+    readonly titleI18n?: Readonly<Partial<Record<Locale, string>>>;
     readonly effects: readonly string[];
+    readonly effectsI18n?: Readonly<Partial<Record<Locale, readonly string[]>>>;
     readonly scope: 'local' | 'platform';
 }
 export interface PluginVerificationOutcome {
     readonly status: 'passed' | 'failed';
     readonly summary: string;
+    readonly summaryI18n?: Readonly<Partial<Record<Locale, string>>>;
     readonly evidence: readonly string[];
+    readonly evidenceI18n?: Readonly<Partial<Record<Locale, readonly string[]>>>;
 }
 /** Plugin-owned optional verification, distinct from generation publication/readiness. */
 export interface PluginVerificationHost {

package/lib/plugin.d.ts

@@ -68,6 +68,6 @@ export interface PluginDefinition<TConfig = unknown> {
 export declare function definePlugin<TConfig = unknown>(definition: PluginDefinition<TConfig>): Readonly<PluginDefinition<TConfig>>;
 export { createDeliveryTarget, type DeliveryTarget } from './delivery-target.js';
 export { PluginStateStore, type JsonValue, type StateScope, type StateRecord, type PersistentStatePort, type StateWriteOptions } from './persistent-state.js';
-export { databaseHostToken, type DatabaseHostConsole, type DatabaseHostModel, type DatabaseHostSelection, type DatabaseHostSelectResult, type DatabaseHostTable, type DatabaseHostType, PluginDatabaseHost, } from './database-host.js';
+export { databaseHostToken, type DatabaseHostConsole, type DatabaseHostModel, type DatabaseHostTransaction, 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, PluginScheduleHost, type ScheduleJobRegistration, } from './schedule-host.js';

package/lib/relational-state.d.ts

@@ -0,0 +1,26 @@
+import { PluginStateStore, type JsonValue } from './persistent-state.js';
+import type { PluginDatabaseHost } from './database-host.js';
+export interface RelationalStateCodec {
+    /** Existing plugin-scoped key to migrate once. */
+    readonly key: string;
+    readonly header: {
+        readonly table: string;
+        readonly definition: Record<string, unknown>;
+    };
+    readonly tables: Readonly<Record<string, Record<string, unknown>>>;
+    /** Explicit additions for an already persisted relational table. */
+    readonly addColumns?: Readonly<Record<string, readonly string[]>>;
+    encode(value: JsonValue): {
+        header: Record<string, unknown>;
+        rows: Record<string, readonly Record<string, unknown>[]>;
+    };
+    decode(header: Record<string, unknown>, rows: Record<string, readonly Record<string, unknown>[]>): JsonValue;
+}
+/**
+ * Reuses PluginStateStore's CAS and admission contract with relational records.
+ * Only registered plugin keys are accepted; ordinary state uses database.state.
+ * Register in setup. Tables, revision and receipts commit or roll back together.
+ */
+export declare function createRelationalStateStore(database: PluginDatabaseHost, codecs: readonly RelationalStateCodec[]): PluginStateStore;
+/** Only for pure database mutations; never wrap external sends or arbitrary side effects. */
+export declare function retryRelationalOperation<T>(operation: () => Promise<T>): Promise<T>;

package/lib/relational-state.js

@@ -0,0 +1,130 @@
+import { randomUUID } from 'node:crypto';
+import { setImmediate } from 'node:timers/promises';
+import { PluginStateStore } from './persistent-state.js';
+/**
+ * Reuses PluginStateStore's CAS and admission contract with relational records.
+ * Only registered plugin keys are accepted; ordinary state uses database.state.
+ * Register in setup. Tables, revision and receipts commit or roll back together.
+ */
+export function createRelationalStateStore(database, codecs) {
+    if (!['sqlite', 'mysql', 'pg'].includes(database.dialect)) {
+        throw new Error(`结构化任务持久化仅支持 SQLite、MySQL、PostgreSQL，当前为 ${database.dialect}；不会自动更换数据库`);
+    }
+    const legacy = database.state;
+    const byKey = new Map(codecs.map(codec => [codec.key, codec]));
+    if (byKey.size !== codecs.length)
+        throw new Error('Duplicate relational state key');
+    for (const codec of codecs) {
+        database.define(codec.header.table, {
+            ...codec.header.definition,
+            storage_id: { type: 'integer', primary: true },
+            storage_revision: { type: 'text', length: 36, nullable: false },
+            storage_present: { type: 'boolean', nullable: false },
+            storage_expires_at: { type: 'bigint', nullable: true },
+        });
+        for (const name of Object.keys(codec.addColumns ?? {})) {
+            if (!Object.hasOwn(codec.tables, name))
+                throw new TypeError(`Unknown relational migration table: ${name}`);
+        }
+        for (const [name, definition] of Object.entries(codec.tables)) {
+            const columns = codec.addColumns?.[name];
+            database.define(name, definition, columns ? { addColumns: columns } : undefined);
+        }
+    }
+    const migrated = new Set();
+    const writeRows = async (transaction, codec, rows) => {
+        for (const name of Object.keys(codec.tables)) {
+            const model = transaction.model(name);
+            await model.delete().where({});
+            for (const row of rows[name] ?? [])
+                await model.insert(row);
+        }
+    };
+    const migrate = async (codec) => {
+        if (migrated.has(codec.key))
+            return;
+        // Read outside the transaction: the old port may use another connection.
+        const old = await legacy.get(codec.key);
+        await retryRelationalOperation(() => database.transaction(async (transaction) => {
+            const model = transaction.model(codec.header.table);
+            if ((await model.select().where({ storage_id: 1 }))[0])
+                return;
+            const encoded = old === undefined ? { header: {}, rows: {} } : codec.encode(old);
+            await model.insert({ ...encoded.header, storage_id: 1, storage_revision: randomUUID(),
+                storage_present: old !== undefined, storage_expires_at: null });
+            await writeRows(transaction, codec, encoded.rows);
+        }));
+        // A durable header is the cutover marker, including an empty/deleted book.
+        // Cleanup failure is safe to retry; never reimport an old deleted task.
+        await retryRelationalOperation(() => legacy.delete(codec.key));
+        migrated.add(codec.key);
+    };
+    return new PluginStateStore(database.owner, {
+        async read(_owner, scope, key) {
+            const codec = byKey.get(key);
+            if (!codec || scope.kind !== 'plugin')
+                throw new Error(`Unregistered relational state key: ${key}`);
+            await migrate(codec);
+            return retryRelationalOperation(() => database.transaction(async (transaction) => {
+                const header = (await transaction.model(codec.header.table).select().where({ storage_id: 1 }))[0];
+                if (!header)
+                    throw new Error('Relational state header is missing');
+                const rows = {};
+                for (const name of Object.keys(codec.tables))
+                    rows[name] = await transaction.model(name).select().orderBy('position');
+                return { revision: String(header.storage_revision),
+                    value: header.storage_present ? codec.decode(header, rows) : null,
+                    // Tombstones must remain visible to CAS, but appear absent to the updater.
+                    expiresAt: header.storage_present ? (header.storage_expires_at == null ? null : Number(header.storage_expires_at)) : 0 };
+            }));
+        },
+        async compareExchange(_owner, scope, key, revision, value, expiresAt) {
+            const codec = byKey.get(key);
+            if (!codec || scope.kind !== 'plugin')
+                throw new Error(`Unregistered relational state key: ${key}`);
+            if (revision === undefined)
+                throw new Error('Relational state must be read before CAS');
+            try {
+                return await database.transaction(async (transaction) => {
+                    const encoded = value === undefined ? { header: {}, rows: {} } : codec.encode(value);
+                    const changed = await transaction.model(codec.header.table).update({ ...encoded.header,
+                        storage_revision: randomUUID(), storage_present: value !== undefined, storage_expires_at: expiresAt,
+                    }).where({ storage_id: 1, storage_revision: revision });
+                    if (changed !== 1)
+                        return false;
+                    await writeRows(transaction, codec, encoded.rows);
+                    return true;
+                });
+            }
+            catch (error) {
+                if (!isRelationalContention(error))
+                    throw error;
+                await setImmediate();
+                return false;
+            }
+        },
+    });
+}
+/** Only for pure database mutations; never wrap external sends or arbitrary side effects. */
+export async function retryRelationalOperation(operation) {
+    for (let attempt = 0;; attempt++) {
+        try {
+            return await operation();
+        }
+        catch (error) {
+            if (attempt >= 63 || !isRelationalContention(error))
+                throw error;
+            await setImmediate();
+        }
+    }
+}
+/** Constraint races and serialization conflicts may replay the pure updater. */
+function isRelationalContention(error) {
+    if (!error || typeof error !== 'object')
+        return false;
+    const value = error;
+    return ['40001', '40P01', '23505', 'SQLITE_BUSY', 'SQLITE_BUSY_SNAPSHOT', 'SQLITE_CONSTRAINT_PRIMARYKEY', 'SQLITE_CONSTRAINT_UNIQUE', 'ER_DUP_ENTRY', 'ER_LOCK_DEADLOCK', 'ER_LOCK_WAIT_TIMEOUT'].includes(value.code ?? '')
+        || [1062, 1213, 1205].includes(value.errno ?? 0)
+        || [5, 517, 1555, 2067].includes(value.errcode ?? 0)
+        || (value.cause !== undefined && isRelationalContention(value.cause));
+}

package/lib/root-config-document.js

@@ -36,6 +36,10 @@ function setValue(document, path, value) {
     for (const [index, segment] of path.slice(0, -1).entries()) {
         const existing = readChild(target, segment, path.slice(0, index + 1));
         if (existing === undefined) {
+            // Inline guard (in addition to assertPath) so the write is visibly safe.
+            if (segment === '__proto__' || segment === 'constructor' || segment === 'prototype') {
+                throw unsafeSegment(segment);
+            }
             const created = {};
             target[segment] = created;
             target = created;
@@ -59,7 +63,11 @@ function removeValue(document, path) {
         target.splice(arrayIndex(segment, target, path), 1);
         return;
     }
-    delete target[segment];
+    if (segment === '__proto__' || segment === 'constructor' || segment === 'prototype') {
+        throw unsafeSegment(segment);
+    }
+    if (Object.hasOwn(target, segment))
+        delete target[segment];
 }
 function cloneDocument(value) {
     const document = structuredClone(value);
@@ -71,13 +79,18 @@ function cloneDocument(value) {
 function readChild(container, segment, path) {
     if (Array.isArray(container))
         return container[arrayIndex(segment, container, path)];
-    return container[segment];
+    // Only own properties count: inherited members (toString, hasOwnProperty, ...)
+    // must never be traversed into or treated as existing config values.
+    return Object.hasOwn(container, segment) ? container[segment] : undefined;
 }
 function writeChild(container, segment, value, path) {
     if (Array.isArray(container)) {
         container[arrayIndex(segment, container, path)] = value;
         return;
     }
+    if (segment === '__proto__' || segment === 'constructor' || segment === 'prototype') {
+        throw unsafeSegment(segment);
+    }
     container[segment] = value;
 }
 function arrayIndex(segment, container, path) {
@@ -99,10 +112,13 @@ function requireContainer(value, path) {
 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>'}`);
+            throw unsafeSegment(segment);
         }
     }
 }
+function unsafeSegment(segment) {
+    return new ConfigPatchPathError(`Unsafe config path segment: ${segment || '<empty>'}`);
+}
 function lastSegment(path) {
     const segment = path[path.length - 1];
     if (!segment)

package/lib/task-storage.d.ts

@@ -0,0 +1,74 @@
+import { type DeliveryTarget } from './delivery-target.js';
+/** Reversible SQL text encoding, including endpoint ids containing NUL. */
+export declare function encodeStorageIdentity(value: string): string;
+export declare function decodeStorageIdentity(value: unknown): string;
+export declare const TASK_TARGET_COLUMNS: {
+    readonly endpoint_adapter: {
+        readonly type: "text";
+        readonly nullable: false;
+    };
+    readonly endpoint_id: {
+        readonly type: "text";
+        readonly nullable: false;
+    };
+    readonly conversation_kind: {
+        readonly type: "text";
+        readonly nullable: false;
+    };
+    readonly conversation_id: {
+        readonly type: "text";
+        readonly nullable: false;
+    };
+    readonly parent_kind: {
+        readonly type: "text";
+        readonly nullable: true;
+    };
+    readonly parent_id: {
+        readonly type: "text";
+        readonly nullable: true;
+    };
+    readonly thread_id: {
+        readonly type: "text";
+        readonly nullable: true;
+    };
+};
+export declare function encodeTaskTarget(target: DeliveryTarget): Record<string, unknown>;
+export declare function decodeTaskTarget(row: Record<string, unknown>): DeliveryTarget;
+export declare const TASK_RECEIPT_COLUMNS: {
+    readonly id: {
+        readonly type: "text";
+        readonly length: 128;
+        readonly primary: true;
+    };
+    readonly position: {
+        readonly type: "integer";
+        readonly nullable: false;
+    };
+    readonly fingerprint: {
+        readonly type: "text";
+        readonly length: 64;
+        readonly nullable: false;
+    };
+    readonly task_id: {
+        readonly type: "text";
+        readonly length: 128;
+        readonly nullable: false;
+    };
+    readonly operation: {
+        readonly type: "text";
+        readonly length: 32;
+        readonly nullable: false;
+    };
+};
+export declare function encodeTaskReceipts(receipts: readonly {
+    id: string;
+    fingerprint: string;
+    taskId: string;
+    operation: string;
+}[]): Record<string, unknown>[];
+export declare function decodeTaskReceipts(rows: readonly Record<string, unknown>[]): {
+    id: string;
+    fingerprint: string;
+    taskId: string;
+    operation: string;
+}[];

package/lib/task-storage.js

@@ -0,0 +1,41 @@
+import { normalizeDeliveryTarget } from './delivery-target.js';
+/** Reversible SQL text encoding, including endpoint ids containing NUL. */
+export function encodeStorageIdentity(value) {
+    return `k1:${value.replaceAll('%', '%25').replaceAll('\0', '%00')}`;
+}
+export function decodeStorageIdentity(value) {
+    if (typeof value !== 'string' || !value.startsWith('k1:'))
+        throw new Error('Invalid stored identity');
+    return value.slice(3).replaceAll('%00', '\0').replaceAll('%25', '%');
+}
+export const TASK_TARGET_COLUMNS = {
+    endpoint_adapter: { type: 'text', nullable: false }, endpoint_id: { type: 'text', nullable: false },
+    conversation_kind: { type: 'text', nullable: false }, conversation_id: { type: 'text', nullable: false },
+    parent_kind: { type: 'text', nullable: true }, parent_id: { type: 'text', nullable: true },
+    thread_id: { type: 'text', nullable: true },
+};
+export function encodeTaskTarget(target) {
+    const value = normalizeDeliveryTarget(target);
+    return { endpoint_adapter: encodeStorageIdentity(value.endpoint.adapter), endpoint_id: encodeStorageIdentity(value.endpoint.id),
+        conversation_kind: value.kind, conversation_id: encodeStorageIdentity(value.id),
+        parent_kind: value.parent?.kind ?? null, parent_id: value.parent ? encodeStorageIdentity(value.parent.id) : null,
+        thread_id: value.threadId === undefined ? null : encodeStorageIdentity(value.threadId) };
+}
+export function decodeTaskTarget(row) {
+    return normalizeDeliveryTarget({ endpoint: { adapter: decodeStorageIdentity(row.endpoint_adapter), id: decodeStorageIdentity(row.endpoint_id) },
+        kind: row.conversation_kind, id: decodeStorageIdentity(row.conversation_id),
+        ...(row.parent_kind == null ? {} : { parent: { kind: row.parent_kind, id: decodeStorageIdentity(row.parent_id) } }),
+        ...(row.thread_id == null ? {} : { threadId: decodeStorageIdentity(row.thread_id) }) });
+}
+export const TASK_RECEIPT_COLUMNS = {
+    id: { type: 'text', length: 128, primary: true }, position: { type: 'integer', nullable: false },
+    fingerprint: { type: 'text', length: 64, nullable: false }, task_id: { type: 'text', length: 128, nullable: false },
+    operation: { type: 'text', length: 32, nullable: false },
+};
+export function encodeTaskReceipts(receipts) {
+    return receipts.map((receipt, position) => ({ id: receipt.id, fingerprint: receipt.fingerprint,
+        task_id: receipt.taskId, operation: receipt.operation, position }));
+}
+export function decodeTaskReceipts(rows) {
+    return rows.map(row => ({ id: String(row.id), fingerprint: String(row.fingerprint), taskId: String(row.task_id), operation: String(row.operation) }));
+}

package/package.json

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