@zhin.js/plugin-runtime 1.1.19 → 1.1.20

package/lib/config-update-declaration.d.ts

@@ -0,0 +1,5 @@
+export interface PluginConfigUpdateDeclaration {
+    readonly featurePaths: readonly (readonly string[])[];
+}
+/** @internal Normalize inert ownership metadata at authoring and snapshot boundaries. */
+export declare function freezePluginConfigUpdate(value: PluginConfigUpdateDeclaration): PluginConfigUpdateDeclaration;

package/lib/config-update-declaration.js

@@ -0,0 +1,15 @@
+/** @internal Normalize inert ownership metadata at authoring and snapshot boundaries. */
+export function freezePluginConfigUpdate(value) {
+    if (!value || typeof value !== 'object' || Object.keys(value).some(key => key !== 'featurePaths') || !Array.isArray(value.featurePaths)) {
+        throw new TypeError('Plugin configUpdate must declare featurePaths');
+    }
+    return Object.freeze({ featurePaths: Object.freeze(Array.from(value.featurePaths, (path) => {
+            if (!Array.isArray(path) || !path.length)
+                throw new TypeError('Plugin configUpdate paths must be safe nonempty paths');
+            const parts = Array.from(path);
+            if (parts.some(part => typeof part !== 'string' || !part || ['__proto__', 'prototype', 'constructor'].includes(part))) {
+                throw new TypeError('Plugin configUpdate paths must be safe nonempty paths');
+            }
+            return Object.freeze(parts);
+        })) });
+}

package/lib/outbound-host.d.ts

@@ -47,8 +47,29 @@ export interface OutboundEndpointInput {
     readonly adapter: string;
     readonly endpointKey: string;
 }
+/**
+ * Per-conversation-kind view of an Endpoint's capability profile (ADR 0044). Structurally the same as
+ * `EndpointKindCapabilities` in `@zhin.js/im-contract`; a missing kind or field means "not supported".
+ */
+export interface OutboundKindCapabilities {
+    readonly feedback?: Readonly<{
+        mode: 'typing' | 'reaction' | 'status-message' | 'none';
+        emoji?: string;
+        text?: string;
+        refreshSeconds?: number;
+    }>;
+    readonly reaction: boolean;
+    readonly edit: boolean;
+    readonly recall: boolean;
+    readonly spool: boolean;
+    /** Messages here must quote an inbound message. */
+    readonly needsReply: boolean;
+    readonly groupInfo: boolean;
+    readonly memberProfile: boolean;
+}
 export interface OutboundEndpointCapabilities {
     readonly operations: readonly OutboundEndpointOperation[];
+    readonly kinds?: Readonly<Partial<Record<'private' | 'group' | 'channel', OutboundKindCapabilities>>>;
 }
 export interface OutboundEditInput {
     readonly message: OutboundMessage;

package/lib/plugin.d.ts

@@ -7,6 +7,9 @@ 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';
+import { type PluginConfigUpdateDeclaration } from './config-update-declaration.js';
+export { freezePluginConfigUpdate } from './config-update-declaration.js';
+export type { PluginConfigUpdateDeclaration } from './config-update-declaration.js';
 export interface PluginMetadata {
     readonly displayName?: string;
     readonly icon?: string;
@@ -48,6 +51,8 @@ export interface PluginDefinition<TConfig = unknown> {
     readonly config?: PluginConfigSchema<TConfig>;
     readonly metadata?: PluginMetadata;
     readonly requires?: readonly Token<unknown>[];
+    /** Fields owned by Features; setup must not capture these as mutable business configuration. */
+    readonly configUpdate?: PluginConfigUpdateDeclaration;
     setup?(context: PluginSetupContext<TConfig>): void | Dispose | Promise<void | Dispose>;
 }
 /**

package/lib/plugin.js

@@ -1,3 +1,5 @@
+import { freezePluginConfigUpdate } from './config-update-declaration.js';
+export { freezePluginConfigUpdate } from './config-update-declaration.js';
 const pluginNamePattern = /^[a-z][a-z0-9-]*$/;
 /**
  * Define the canonical `plugin.ts` entry point.
@@ -28,6 +30,7 @@ export function definePlugin(definition) {
         ...definition,
         metadata: definition.metadata ? Object.freeze({ ...definition.metadata }) : undefined,
         requires: Object.freeze([...(definition.requires ?? [])]),
+        ...(definition.configUpdate !== undefined ? { configUpdate: freezePluginConfigUpdate(definition.configUpdate) } : {}),
     });
 }
 // The application facade exposes these Host contracts beside definePlugin.

package/lib/snapshot.d.ts

@@ -4,6 +4,7 @@ import type { Dispose } from './dispose.js';
 import type { GenerationHandoff } from './handoff.js';
 import type { CapabilityId, FeatureId, PluginId, TokenId } from './identity.js';
 import type { PluginMetadata } from './plugin.js';
+import { type PluginConfigUpdateDeclaration } from './config-update-declaration.js';
 export interface PluginNodeSnapshot {
     readonly id: PluginId;
     readonly instanceKey: string;
@@ -16,6 +17,7 @@ export interface PluginNodeSnapshot {
     readonly metadata?: PluginMetadata;
     /** Immutable schema declaration belonging to this committed generation. */
     readonly configSchema?: Readonly<Record<string, unknown>>;
+    readonly configUpdate?: PluginConfigUpdateDeclaration;
 }
 export interface RuntimeSnapshot {
     readonly generation: number;

package/lib/snapshot.js

@@ -1,4 +1,5 @@
 import { collectGenerationAdmissions, replaceGenerationAdmissions, } from './admission.js';
+import { freezePluginConfigUpdate } from './config-update-declaration.js';
 export class GenerationConflictError extends Error {
     expected;
     actual;
@@ -214,8 +215,9 @@ export function createSnapshotView(generation, state) {
     return Object.freeze({
         ...state,
         generation,
-        tree: readonlyMap([...state.tree].map(([owner, node]) => [owner, node.configSchema
-                ? Object.freeze({ ...node, configSchema: freezeSchema(structuredClone(node.configSchema)) })
+        tree: readonlyMap([...state.tree].map(([owner, node]) => [owner, node.configSchema || node.configUpdate
+                ? Object.freeze({ ...node, ...(node.configSchema ? { configSchema: freezeSchema(structuredClone(node.configSchema)) } : {}),
+                    ...(node.configUpdate ? { configUpdate: freezePluginConfigUpdate(node.configUpdate) } : {}) })
                 : node])),
         config: readonlyMap(state.config),
         resources: readonlyMap([...state.resources].map(([owner, resources]) => [owner, readonlyMap(resources)])),

package/lib/token.d.ts

@@ -7,6 +7,8 @@ export interface Token<T> {
 }
 export declare function createToken<T>(id: string, description?: string): Token<T>;
 export declare function createRootPrivateToken<T>(id: string, description?: string): Token<T>;
+/** @internal Verify token identity before accepting a generation-private binding. */
+export declare function isRootPrivateToken(token: Token<unknown>): boolean;
 /** A Root-private capability readable only while projecting its owning Feature. */
 export declare function createFeaturePrivateToken<T>(id: string, feature: FeatureId, description?: string): Token<T>;
 /** @internal The actual candidate Root Scope never enters the Feature context. */

package/lib/token.js

@@ -10,6 +10,8 @@ export function createRootPrivateToken(id, description) {
     rootPrivateTokens.add(token);
     return Object.freeze(token);
 }
+/** @internal Verify token identity before accepting a generation-private binding. */
+export function isRootPrivateToken(token) { return rootPrivateTokens.has(token); }
 /** A Root-private capability readable only while projecting its owning Feature. */
 export function createFeaturePrivateToken(id, feature, description) {
     const token = createRootPrivateToken(id, description);

package/package.json

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