@zhin.js/plugin-runtime 1.1.16 → 1.1.18

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-events.d.ts

@@ -0,0 +1,47 @@
+import type { Dispose } from './dispose.js';
+import type { CapabilityId, PluginId } from './identity.js';
+/** Planned invalidation is distinct from the instances actually replaced at commit. */
+export interface HmrReloadScope {
+    readonly fullRoot: boolean;
+    readonly plugins: readonly PluginId[];
+    readonly capabilities: readonly CapabilityId[];
+}
+export interface HmrEventDetails {
+    readonly trigger: 'manual' | 'source';
+    readonly changed: readonly string[];
+    readonly planned: HmrReloadScope;
+    readonly previousGeneration: number;
+    readonly activeGeneration: number;
+    readonly receiver: Readonly<{
+        owner: PluginId;
+        creationGeneration: number;
+        state: 'current' | 'replaced';
+    }>;
+}
+export type HmrOutcome = 'committed' | 'unchanged' | 'rejected' | 'cancelled' | 'restart-required';
+export interface HmrResumeDetails extends HmrEventDetails {
+    readonly outcome: HmrOutcome;
+    readonly reason?: 'root-stopping';
+    readonly replaced: readonly PluginId[];
+}
+/** A control-phase signal, not a command to cancel the plugin's accepted business work. */
+export interface PluginLifecycleEvent<TDetails> {
+    readonly signal: AbortSignal;
+    readonly details: Readonly<TDetails>;
+}
+export interface PluginLifecycleEventMap {
+    readonly 'hmr.pause': PluginLifecycleEvent<HmrEventDetails>;
+    readonly 'hmr.resume': PluginLifecycleEvent<HmrResumeDetails>;
+}
+export interface PluginEventSubscriptions {
+    /** Subscription belongs to this concrete plugin instance, including when its Scope is reused. */
+    on<TName extends keyof PluginLifecycleEventMap>(name: TName, handler: (event: PluginLifecycleEventMap[TName]) => void | Promise<void>): Dispose;
+}
+/** @internal Runtime delivery authority; never exposed through a setup context or resource snapshot. */
+export interface PluginEventChannel {
+    readonly events: PluginEventSubscriptions;
+    dispatch<TName extends keyof PluginLifecycleEventMap>(name: TName, event: PluginLifecycleEventMap[TName]): Promise<void>;
+    dispose(): void;
+}
+/** @internal One instance-owned subscription record; no inherited or process-wide listener registry. */
+export declare function createPluginEventChannel(): PluginEventChannel;

package/lib/plugin-events.js

@@ -0,0 +1,30 @@
+/** @internal One instance-owned subscription record; no inherited or process-wide listener registry. */
+export function createPluginEventChannel() {
+    const handlers = {
+        'hmr.pause': new Set(), 'hmr.resume': new Set(),
+    };
+    let disposed = false;
+    return Object.freeze({
+        events: Object.freeze({
+            on(name, handler) {
+                if (disposed)
+                    throw new Error('Plugin event subscriptions are disposed');
+                handlers[name].add(handler);
+                return () => { handlers[name].delete(handler); };
+            },
+        }),
+        async dispatch(name, event) {
+            if (disposed)
+                throw new Error('Plugin event subscriptions are disposed');
+            const results = await Promise.allSettled([...handlers[name]].map(handler => Promise.resolve().then(() => handler(event))));
+            const errors = results.flatMap(result => result.status === 'rejected' ? [result.reason] : []);
+            if (errors.length)
+                throw new AggregateError(errors, `Plugin ${name} handlers failed`);
+        },
+        dispose() {
+            disposed = true;
+            handlers['hmr.pause'].clear();
+            handlers['hmr.resume'].clear();
+        },
+    });
+}

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

@@ -6,6 +6,7 @@ import type { Dispose, DisposeStack } from './dispose.js';
 import type { GenerationHandoffRegistry } from './handoff.js';
 import type { FeatureId, PluginId } from './identity.js';
 import type { Scope, Token } from './token.js';
+import type { PluginEventSubscriptions } from './plugin-events.js';
 export interface PluginMetadata {
     readonly displayName?: string;
     readonly icon?: string;
@@ -27,6 +28,7 @@ export interface PluginInstanceView {
     readonly role: 'root' | 'child';
 }
 export interface PluginSetupContext<TConfig = unknown> {
+    readonly events: PluginEventSubscriptions;
     readonly signal: AbortSignal;
     readonly plugin: PluginInstanceView;
     readonly config: ConfigView<TConfig>;
@@ -40,6 +42,7 @@ export interface PluginSetupContext<TConfig = unknown> {
      */
     addFeature<TDefinition>(feature: FeatureId | string, localName: string, definition: TDefinition): void;
 }
+export { type PluginEventSubscriptions, type PluginLifecycleEvent, type PluginLifecycleEventMap, type HmrEventDetails, type HmrResumeDetails, type HmrReloadScope, type HmrOutcome, } from './plugin-events.js';
 export interface PluginDefinition<TConfig = unknown> {
     readonly name: string;
     readonly config?: PluginConfigSchema<TConfig>;
@@ -69,5 +72,7 @@ export declare function definePlugin<TConfig = unknown>(definition: PluginDefini
 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 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 { outboundHostToken, type OutboundConversation, type OutboundEditInput, type OutboundEndpointCapabilities, type OutboundEndpointInput, type OutboundEndpointOperation, type OutboundHost, type OutboundCaptureInput, type CapturedOutboundOperation, 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';
+export { DataMigrationError, pluginDataMigrationProviderToken, type DataMigrationCandidate, type DataMigrationInventory, type DataMigrationRequest, type PrepareDataMigrationRequest, type DataMigrationPlan, type ApplyDataMigrationRequest, type DataMigrationReceipt, type ResumeDataMigrationRequest, type RestoreDataMigrationRequest, type InspectDataMigrationRequest, type DataMigrationInspection, type PluginDataMigrationProvider, } from './data-migration.js';
+export { TargetMigrationScopes, targetMigrationDigest, orderedMigrationRows, createRelationalTargetMigration, type TargetMigrationRows, type TargetMigrationWrite, type RelationalTargetMigrationUnit, type RelationalTargetMigrationOptions, } from './relational-target-migration.js';

package/lib/plugin.js

@@ -36,3 +36,5 @@ export { PluginStateStore } from './persistent-state.js';
 export { databaseHostToken, PluginDatabaseHost, } from './database-host.js';
 export { outboundHostToken, } from './outbound-host.js';
 export { scheduleHostToken, PluginScheduleHost, } from './schedule-host.js';
+export { DataMigrationError, pluginDataMigrationProviderToken, } from './data-migration.js';
+export { TargetMigrationScopes, targetMigrationDigest, orderedMigrationRows, createRelationalTargetMigration, } from './relational-target-migration.js';

package/lib/relational-state.d.ts

@@ -8,6 +8,8 @@ export interface RelationalStateCodec {
         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>[]>;

package/lib/relational-state.js

@@ -22,8 +22,14 @@ export function createRelationalStateStore(database, codecs) {
             storage_present: { type: 'boolean', nullable: false },
             storage_expires_at: { type: 'bigint', nullable: true },
         });
-        for (const [name, definition] of Object.entries(codec.tables))
-            database.define(name, definition);
+        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) => {

package/lib/relational-target-migration.d.ts

@@ -0,0 +1,68 @@
+import type { DatabaseHostTransaction, PluginDatabaseHost } from './database-host.js';
+import { type DeliveryTarget } from './delivery-target.js';
+import { type DataMigrationCandidate, type PluginDataMigrationProvider } from './data-migration.js';
+import type { JsonValue } from './persistent-state.js';
+type Row = Record<string, unknown>;
+/** One business-key row set; identical keyless rows remain an indivisible group. */
+export interface TargetMigrationRows {
+    readonly table: string;
+    readonly query: Readonly<Row>;
+    readonly rows: readonly Row[];
+}
+export interface TargetMigrationWrite {
+    readonly before: TargetMigrationRows;
+    readonly after: TargetMigrationRows;
+    readonly patch: Readonly<Row>;
+}
+export interface RelationalTargetMigrationUnit {
+    readonly id: string;
+    readonly title: string;
+    readonly scope: string;
+    readonly status: DataMigrationCandidate['status'];
+    readonly records: readonly TargetMigrationRows[];
+    readonly summary: Readonly<Record<string, JsonValue>>;
+    readonly authorizationCandidates?: readonly JsonValue[];
+}
+export interface RelationalTargetMigrationOptions {
+    /** Owner-qualified Host facade; raw process tables never enter the provider. */
+    readonly database: PluginDatabaseHost;
+    readonly domain: string;
+    readonly title: string;
+    readonly sourceVersion: string;
+    /** All tables that this domain is allowed to read or change. */
+    readonly tables: readonly string[];
+    readonly scopes: TargetMigrationScopes;
+    readUnits(reader: DatabaseHostTransaction): Promise<readonly RelationalTargetMigrationUnit[]>;
+    /** Rewrites routing only. Domain state, deadlines, IDs and revision fields are retained. */
+    rewrite(unit: RelationalTargetMigrationUnit, target: DeliveryTarget): {
+        readonly writes: readonly TargetMigrationWrite[];
+        readonly destinationScope: string;
+    };
+}
+/** Stable, lossless digest; this does not impose the small-object StateStore size limit. */
+export declare function targetMigrationDigest(value: unknown): string;
+export declare function orderedMigrationRows(rows: readonly Row[]): readonly Row[];
+/** Per-instance scope admission. Existing work drains; unrelated scopes continue. */
+export declare class TargetMigrationScopes {
+    #private;
+    constructor(input: Readonly<{
+        pending: (scope: string) => boolean;
+    }>);
+    bindInitialization(initialize: () => Promise<void>): void;
+    run<T>(input: Readonly<{
+        scope: string;
+        run: () => Promise<T>;
+    }>): Promise<T>;
+    pause(input: Readonly<{
+        planId: string;
+        scopes: readonly string[];
+        persist: () => Promise<void>;
+    }>): Promise<void>;
+    drained(scopes: readonly string[]): boolean;
+    maintenance(planId: string, scopes: readonly string[]): 'paused' | 'resumed' | 'unknown';
+    restorePause(planId: string, scopes: readonly string[]): void;
+    resume(planId: string, scopes: readonly string[]): void;
+}
+/** Shared only by the concrete game and subscription target migrations. No raw-SQL or generic schema discovery. */
+export declare function createRelationalTargetMigration(options: RelationalTargetMigrationOptions): PluginDataMigrationProvider;
+export {};