@zhin.js/plugin-runtime 1.1.6 → 1.1.8

package/lib/admission.d.ts

@@ -7,6 +7,8 @@ export declare class GenerationAdmissionGate {
     constructor();
     get active(): boolean;
     acquire(): (() => void) | undefined;
+    /** Observe the first commit which publishes this generation. */
+    onActivate(listener: () => void): () => void;
     /**
      * Observe retirement of the generation that owns this gate. The callback is
      * synchronous and must not fail; it is intended for closing process-owned
@@ -19,6 +21,7 @@ export declare function createGenerationAdmissionGate(): GenerationAdmissionGate
 /** Resource hook used by CapabilityContext to bind an ingress dependency. */
 export declare const generationAdmissionBinder: unique symbol;
 export interface GenerationAdmissionBindable<T> {
+    /** @internal Runtime lifecycle wiring; never called by plugin authors. */
     [generationAdmissionBinder](gate: GenerationAdmissionGate): T;
 }
 /** Snapshot value hook used to declare lifecycle-owned ingress gates. */

package/lib/admission.js

@@ -6,6 +6,7 @@
 export class GenerationAdmissionGate {
     constructor() {
         admissionState.set(this, { active: false });
+        admissionActivationListeners.set(this, new Set());
         admissionDeactivationListeners.set(this, new Set());
     }
     get active() {
@@ -15,6 +16,18 @@ export class GenerationAdmissionGate {
         const state = admissionState.get(this);
         return state?.active ? 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); };
+    }
     /**
      * Observe retirement of the generation that owns this gate. The callback is
      * synchronous and must not fail; it is intended for closing process-owned
@@ -50,6 +63,7 @@ export class GenerationAdmissionGate {
 }
 const admissionState = new WeakMap();
 const admissionOwners = new WeakMap();
+const admissionActivationListeners = new WeakMap();
 const admissionDeactivationListeners = new WeakMap();
 export function createGenerationAdmissionGate() {
     return new GenerationAdmissionGate();
@@ -111,6 +125,17 @@ export function replaceGenerationAdmissions(previous, next, owner, acquireNext)
     }
     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) {

package/lib/database-host.d.ts

@@ -128,6 +128,7 @@ export declare function unwrapPluginDatabaseHost(host: DatabaseHost | PluginData
  * The owner encoding keeps `root/a` and `root/a/b` disjoint, so a parent
  * facade cannot accidentally enumerate a descendant's tables.
  */
+/** @public Plugin-facing database facade bound to the current owner. */
 export declare const databaseHostToken: import("./token.js").Token<PluginDatabaseHost>;
 /** Root-only process host for CLI composition and Console administration. */
 export declare const databaseRootHostToken: import("./token.js").Token<DatabaseHost>;

package/lib/database-host.js

@@ -66,6 +66,7 @@ function assertLogicalResourceName(name) {
  * The owner encoding keeps `root/a` and `root/a/b` disjoint, so a parent
  * facade cannot accidentally enumerate a descendant's tables.
  */
+/** @public Plugin-facing database facade bound to the current owner. */
 export const databaseHostToken = createToken('zhin.database.host', 'Plugin Runtime scoped database host');
 /** Root-only process host for CLI composition and Console administration. */
 export const databaseRootHostToken = createToken('zhin.database.root-host', 'Plugin Runtime root database host');

package/lib/index.d.ts

@@ -1,3 +1,7 @@
+/**
+ * Generation-owned plugin definitions, capability tokens, and Host resources.
+ * @module @zhin.js/plugin-runtime
+ */
 /** @internal Runtime 内部：CapabilitySlot（feature 与 projection 之间的载体）。 */
 export * from './capability.js';
 export * from './dispose.js';

package/lib/index.js

@@ -1,3 +1,7 @@
+/**
+ * Generation-owned plugin definitions, capability tokens, and Host resources.
+ * @module @zhin.js/plugin-runtime
+ */
 /** @internal Runtime 内部：CapabilitySlot（feature 与 projection 之间的载体）。 */
 export * from './capability.js';
 export * from './dispose.js';

package/lib/outbound-host.d.ts

@@ -42,6 +42,22 @@ export interface OutboundRecallInput {
     readonly endpointKey: string;
     readonly message: OutboundMessage;
 }
+export type OutboundEndpointOperation = 'recall' | 'edit' | 'reaction' | 'typing';
+export interface OutboundEndpointInput {
+    readonly adapter: string;
+    readonly endpointKey: string;
+}
+export interface OutboundEndpointCapabilities {
+    readonly operations: readonly OutboundEndpointOperation[];
+}
+export interface OutboundEditInput extends OutboundEndpointInput {
+    readonly message: OutboundMessage;
+    readonly content: unknown;
+}
+export interface OutboundTypingInput extends OutboundEndpointInput {
+    readonly conversation: OutboundMessage['conversation'];
+    readonly active?: boolean;
+}
 /** Structured message identity; structurally compatible with IM MessageRef. */
 export interface OutboundMessage {
     readonly conversation: OutboundConversation & Readonly<{
@@ -53,6 +69,10 @@ export interface OutboundMessage {
     readonly id: string;
 }
 export interface OutboundHost {
+    /** 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. */
+    capabilities?(input: OutboundEndpointInput): OutboundEndpointCapabilities | undefined;
     /** Returns platform message id when available (activity-feedback needs it). */
     send(input: OutboundSendInput): Promise<string | null>;
     /** Optional: platform message reactions (icqq group emoji, etc.). */
@@ -60,5 +80,10 @@ export interface OutboundHost {
     removeReaction?(input: OutboundRemoveReactionInput): Promise<void>;
     /** Optional: recall/delete a status message (activity-feedback autoRemove). */
     recall?(input: OutboundRecallInput): Promise<void>;
+    /** Optional: update a previously sent status message. */
+    edit?(input: OutboundEditInput): Promise<string | null>;
+    /** Optional: toggle the platform-native typing indicator. */
+    typing?(input: OutboundTypingInput): Promise<void>;
 }
+/** @public Plugin-facing cross-platform outbound messaging Host. */
 export declare const outboundHostToken: import("./token.js").Token<OutboundHost>;

package/lib/outbound-host.js

@@ -1,2 +1,3 @@
 import { createToken } from './token.js';
+/** @public Plugin-facing cross-platform outbound messaging Host. */
 export const outboundHostToken = createToken('zhin.outbound.host', 'Plugin Runtime outbound push host');

package/lib/plugin.d.ts

@@ -1,3 +1,7 @@
+/**
+ * Canonical plugin definition consumed from `zhin.js`.
+ * @module zhin.js
+ */
 import type { Dispose, DisposeStack } from './dispose.js';
 import type { GenerationHandoffRegistry } from './handoff.js';
 import type { FeatureId, PluginId } from './identity.js';
@@ -27,6 +31,7 @@ export interface PluginSetupContext<TConfig = unknown> {
     /**
      * Registers an in-memory definition through the same validation and
      * projection transaction used by convention-discovered capabilities.
+     * @internal Runtime bridge for feature installers; plugin authors use convention files.
      */
     addFeature<TDefinition>(feature: FeatureId | string, localName: string, definition: TDefinition): void;
 }
@@ -36,4 +41,25 @@ export interface PluginDefinition<TConfig = unknown> {
     readonly requires?: readonly Token<unknown>[];
     setup?(context: PluginSetupContext<TConfig>): void | Dispose | Promise<void | Dispose>;
 }
+/**
+ * Define the canonical `plugin.ts` entry point.
+ * Setup runs against one candidate generation and may return its disposer.
+ *
+ * @public
+ * @example
+ * ```ts
+ * import { definePlugin } from 'zhin.js';
+ *
+ * // plugin.ts
+ * export default definePlugin({
+ *   name: 'hello',
+ * });
+ * ```
+ *
+ * Put capabilities in convention files such as `commands/hello.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 { 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';

package/lib/plugin.js

@@ -1,4 +1,22 @@
 const pluginNamePattern = /^[a-z][a-z0-9-]*$/;
+/**
+ * Define the canonical `plugin.ts` entry point.
+ * Setup runs against one candidate generation and may return its disposer.
+ *
+ * @public
+ * @example
+ * ```ts
+ * import { definePlugin } from 'zhin.js';
+ *
+ * // plugin.ts
+ * export default definePlugin({
+ *   name: 'hello',
+ * });
+ * ```
+ *
+ * Put capabilities in convention files such as `commands/hello.ts`, each with
+ * one default export.
+ */
 export function definePlugin(definition) {
     if (!pluginNamePattern.test(definition.name)) {
         throw new TypeError(`Invalid plugin name: ${definition.name}`);
@@ -9,3 +27,7 @@ export function definePlugin(definition) {
         requires: Object.freeze([...(definition.requires ?? [])]),
     });
 }
+// The application facade exposes these Host contracts beside definePlugin.
+export { databaseHostToken, } from './database-host.js';
+export { outboundHostToken, } from './outbound-host.js';
+export { scheduleHostToken, } from './schedule-host.js';

package/lib/root-controller.d.ts

@@ -1,29 +1,30 @@
 import type { PluginId } from './identity.js';
-import { type PreparedGeneration, type RuntimeSnapshot, type SnapshotReader, type SnapshotState } from './snapshot.js';
+import { type CommittedGeneration, type PreparedGeneration, type RuntimeSnapshot, type SnapshotReader, type SnapshotState } from './snapshot.js';
 export type RootState = 'idle' | 'running' | 'stopping' | 'stopped' | 'failed';
-export type PrepareGeneration = (current: RuntimeSnapshot, signal: AbortSignal) => PreparedGeneration | Promise<PreparedGeneration>;
-export type PrepareTransaction = (current: RuntimeSnapshot, signal: AbortSignal) => PreparedGeneration | undefined | Promise<PreparedGeneration | undefined>;
+export type PrepareGeneration<TState = undefined> = (current: RuntimeSnapshot, signal: AbortSignal) => PreparedGeneration<TState> | Promise<PreparedGeneration<TState>>;
+export type PrepareTransaction<TState = undefined> = (current: RuntimeSnapshot, signal: AbortSignal) => PreparedGeneration<TState> | undefined | Promise<PreparedGeneration<TState> | undefined>;
 export type ControlErrorHandler = (error: unknown) => void;
-export interface GenerationCommitEvent {
-    readonly previous: RuntimeSnapshot;
-    readonly current: RuntimeSnapshot;
+export interface GenerationCommitEvent<TState = undefined> {
+    readonly previous: CommittedGeneration<TState>;
+    readonly current: CommittedGeneration<TState>;
 }
-export type GenerationCommitListener = (event: GenerationCommitEvent) => void;
+export type GenerationCommitListener<TState = undefined> = (event: GenerationCommitEvent<TState>) => void | Promise<void>;
 export declare class RootIntegrityError extends Error {
     constructor(message: string, options?: ErrorOptions);
 }
-export declare class RootController {
+export declare class RootController<TState = undefined> {
     #private;
     private readonly onControlError;
     readonly snapshots: SnapshotReader;
-    constructor(initial: SnapshotState, onControlError?: ControlErrorHandler);
+    constructor(initial: SnapshotState, onControlError?: ControlErrorHandler, ...state: [TState] extends [undefined] ? [initialState?: undefined] : [initialState: TState]);
     get state(): RootState;
     get generation(): number;
     get snapshot(): RuntimeSnapshot;
+    get committed(): CommittedGeneration<TState>;
     /** Observe successful generation commits, including the initial start. */
-    onGenerationCommit(listener: GenerationCommitListener): () => void;
-    start(prepare: PrepareGeneration): Promise<RuntimeSnapshot>;
-    transact(prepare: PrepareTransaction): Promise<RuntimeSnapshot>;
-    reload(_target: PluginId | string, prepare: PrepareTransaction): Promise<RuntimeSnapshot>;
+    onGenerationCommit(listener: GenerationCommitListener<TState>): () => void;
+    start(prepare: PrepareGeneration<TState>): Promise<RuntimeSnapshot>;
+    transact(prepare: PrepareTransaction<TState>): Promise<RuntimeSnapshot>;
+    reload(_target: PluginId | string, prepare: PrepareTransaction<TState>): Promise<RuntimeSnapshot>;
     stop(): Promise<void>;
 }

package/lib/root-controller.js

@@ -16,9 +16,9 @@ export class RootController {
     #stopRequested = false;
     #activeTransaction;
     #generationCommitListeners = new Set();
-    constructor(initial, onControlError = () => undefined) {
+    constructor(initial, onControlError = () => undefined, ...state) {
         this.onControlError = onControlError;
-        this.#snapshotStore = new SnapshotStore(initial, (error) => this.#failIntegrity(error));
+        this.#snapshotStore = new SnapshotStore(initial, (error) => this.#failIntegrity(error), ...state);
         const store = this.#snapshotStore;
         this.snapshots = Object.freeze({
             acquire: () => {
@@ -39,6 +39,9 @@ export class RootController {
     get snapshot() {
         return this.#snapshotStore.current;
     }
+    get committed() {
+        return this.#snapshotStore.committed;
+    }
     /** Observe successful generation commits, including the initial start. */
     onGenerationCommit(listener) {
         this.#generationCommitListeners.add(listener);
@@ -141,21 +144,23 @@ export class RootController {
         return result;
     }
     #commitGeneration(expectedGeneration, prepared) {
-        const previous = this.#snapshotStore.current;
-        const snapshot = this.#snapshotStore.commit(expectedGeneration, prepared);
-        const event = Object.freeze({ previous, current: snapshot });
+        const previous = this.#snapshotStore.committed;
+        const current = this.#snapshotStore.commit(expectedGeneration, prepared);
+        const event = Object.freeze({ previous, current });
         const listeners = [...this.#generationCommitListeners];
         queueMicrotask(() => {
             for (const listener of listeners) {
                 try {
-                    listener(event);
+                    void Promise.resolve(listener(event)).catch((error) => {
+                        this.#reportControlError(error);
+                    });
                 }
                 catch (error) {
                     this.#reportControlError(error);
                 }
             }
         });
-        return snapshot;
+        return current.snapshot;
     }
     #reportControlError(error) {
         try {

package/lib/schedule-host.d.ts

@@ -37,7 +37,7 @@ export declare function unqualifyPluginScheduleId(owner: PluginId, id: string):
 export declare function createPluginScheduleHost(owner: PluginId, host: ScheduleHost): PluginScheduleHost;
 /** See unwrapPluginDatabaseHost: preserves legacy custom RootResource installers. */
 export declare function unwrapPluginScheduleHost(host: ScheduleHost | PluginScheduleHost): ScheduleHost;
-/** Plugin-facing token; Runtime injects a facade bound to the current owner. */
+/** @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. */
 export declare const scheduleRootHostToken: import("./token.js").Token<ScheduleHost>;

package/lib/schedule-host.js

@@ -46,7 +46,7 @@ function assertLogicalJobId(id) {
         throw new TypeError(`Invalid plugin schedule id: ${id}`);
     }
 }
-/** Plugin-facing token; Runtime injects a facade bound to the current owner. */
+/** @public Plugin-facing token; Runtime injects a facade bound to the current owner. */
 export const scheduleHostToken = createToken('zhin.schedule.host', 'Plugin Runtime scoped solar cron host');
 /** Root-only process scheduler for CLI composition and Console administration. */
 export const scheduleRootHostToken = createToken('zhin.schedule.root-host', 'Plugin Runtime root solar cron host');

package/lib/snapshot.d.ts

@@ -22,11 +22,20 @@ export interface RuntimeSnapshot {
     readonly projections: ReadonlyMap<FeatureId, unknown>;
 }
 export type SnapshotState = Omit<RuntimeSnapshot, 'generation'>;
-export interface PreparedGeneration {
+interface PreparedGenerationBase {
     readonly snapshot: SnapshotState;
     readonly dispose: Dispose;
     readonly handoff?: GenerationHandoff;
 }
+export type PreparedGeneration<TState = undefined> = PreparedGenerationBase & ([TState] extends [undefined] ? {
+    readonly state?: undefined;
+} : {
+    readonly state: TState;
+});
+export interface CommittedGeneration<TState = undefined> {
+    readonly snapshot: RuntimeSnapshot;
+    readonly state: TState;
+}
 export declare class GenerationConflictError extends Error {
     readonly expected: number;
     readonly actual: number;
@@ -46,14 +55,16 @@ export interface SnapshotReader {
     acquire(): SnapshotLease;
     owns(lease: SnapshotLease): boolean;
 }
-export declare class SnapshotStore implements SnapshotReader {
+export declare class SnapshotStore<TState = undefined> implements SnapshotReader {
     #private;
     private readonly onDisposalError;
-    constructor(initial: SnapshotState, onDisposalError?: (error: unknown) => void);
+    constructor(initial: SnapshotState, onDisposalError?: (error: unknown) => void, ...state: [TState] extends [undefined] ? [initialState?: undefined] : [initialState: TState]);
     get current(): RuntimeSnapshot;
+    /** Complete active record; snapshot and state always belong to one generation. */
+    get committed(): CommittedGeneration<TState>;
     acquire(): SnapshotLease;
     owns(lease: SnapshotLease): boolean;
-    commit(expectedGeneration: number, prepared: PreparedGeneration): RuntimeSnapshot;
+    commit(expectedGeneration: number, prepared: PreparedGeneration<TState>): CommittedGeneration<TState>;
     close(): Promise<void>;
 }
 export declare function createSnapshotView(generation: number, state: SnapshotState): RuntimeSnapshot;

package/lib/snapshot.js

@@ -36,12 +36,16 @@ export class SnapshotStore {
     #retired = new Set();
     #leases = new WeakSet();
     #closed = false;
-    constructor(initial, onDisposalError = () => undefined) {
+    constructor(initial, onDisposalError = () => undefined, ...state) {
         this.onDisposalError = onDisposalError;
+        const initialState = state[0];
         const snapshot = createSnapshotView(0, initial);
+        const committed = Object.freeze({ snapshot, state: initialState });
         const admissions = collectSnapshotAdmissions(snapshot);
         const record = {
             snapshot,
+            state: initialState,
+            committed,
             dispose: () => undefined,
             admissions,
             leases: 0,
@@ -53,6 +57,10 @@ export class SnapshotStore {
     get current() {
         return this.#current.snapshot;
     }
+    /** Complete active record; snapshot and state always belong to one generation. */
+    get committed() {
+        return this.#current.committed;
+    }
     acquire() {
         if (this.#closed)
             throw new Error('SnapshotStore is closed');
@@ -75,9 +83,13 @@ export class SnapshotStore {
         }
         const previous = this.#current;
         const snapshot = createSnapshotView(expectedGeneration + 1, prepared.snapshot);
+        const state = prepared.state;
+        const committed = Object.freeze({ snapshot, state });
         const admissions = collectSnapshotAdmissions(snapshot);
         const next = {
             snapshot,
+            state,
+            committed,
             dispose: prepared.dispose,
             admissions,
             leases: 0,
@@ -90,7 +102,7 @@ export class SnapshotStore {
         previous.retired = true;
         this.#retired.add(previous);
         this.#disposeIfReady(previous);
-        return this.#current.snapshot;
+        return this.#current.committed;
     }
     async close() {
         if (this.#closed)

package/lib/token.d.ts

@@ -6,6 +6,7 @@ export interface Token<T> {
     readonly _type?: () => T;
 }
 export declare function createToken<T>(id: string, description?: string): Token<T>;
+export declare function createRootPrivateToken<T>(id: string, description?: string): Token<T>;
 export declare class Scope {
     #private;
     readonly owner: PluginId;

package/lib/token.js

@@ -1,8 +1,14 @@
 import { DisposeStack } from './dispose.js';
 import { tokenId } from './identity.js';
+const rootPrivateTokens = new WeakSet();
 export function createToken(id, description) {
     return Object.freeze({ id: tokenId(id), description });
 }
+export function createRootPrivateToken(id, description) {
+    const token = { id: tokenId(id), description };
+    rootPrivateTokens.add(token);
+    return Object.freeze(token);
+}
 export class Scope {
     owner;
     parent;
@@ -20,20 +26,36 @@ export class Scope {
         if (this.#bindings.has(token.id)) {
             throw new Error(`Duplicate resource ${token.id} in ${this.owner}`);
         }
-        this.#bindings.set(token.id, Object.freeze({ owner: this.owner, value }));
+        this.#bindings.set(token.id, Object.freeze({
+            owner: this.owner,
+            value,
+            rootPrivate: rootPrivateTokens.has(token),
+            token,
+        }));
         if (dispose)
             this.disposers.add(dispose);
     }
     use(token) {
         const binding = this.#bindings.get(token.id);
-        if (binding)
-            return binding.value;
-        if (this.parent)
-            return this.parent.use(token);
+        if (binding) {
+            if (!binding.rootPrivate || binding.token === token)
+                return binding.value;
+            throw new Error(`Missing resource ${token.id} for ${this.owner}`);
+        }
+        const inherited = this.parent
+            ? this.parent.#resolveForDescendant(token.id)
+            : undefined;
+        if (inherited?.status === 'found')
+            return inherited.binding.value;
         throw new Error(`Missing resource ${token.id} for ${this.owner}`);
     }
     has(token) {
-        return this.#bindings.has(token.id) || Boolean(this.parent?.has(token));
+        const binding = this.#bindings.get(token.id);
+        if (binding)
+            return !binding.rootPrivate || binding.token === token;
+        return this.parent
+            ? this.parent.#resolveForDescendant(token.id)?.status === 'found'
+            : false;
     }
     seal() {
         this.#sealed = true;
@@ -45,8 +67,19 @@ export class Scope {
         const result = this.parent
             ? new Map(this.parent.snapshot())
             : new Map();
-        for (const [id, binding] of this.#bindings)
-            result.set(id, binding.value);
+        for (const [id, binding] of this.#bindings) {
+            if (!binding.rootPrivate)
+                result.set(id, binding.value);
+        }
         return result;
     }
+    #resolveForDescendant(id) {
+        const binding = this.#bindings.get(id);
+        if (binding) {
+            return binding.rootPrivate
+                ? Object.freeze({ status: 'blocked' })
+                : Object.freeze({ status: 'found', binding });
+        }
+        return this.parent ? this.parent.#resolveForDescendant(id) : undefined;
+    }
 }

package/package.json

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