@zhin.js/plugin-runtime 1.1.18 → 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/database-host.d.ts

@@ -9,6 +9,13 @@ export interface DatabaseHostSelection {
     limit(count: number): DatabaseHostSelection;
     then<TResult1 = Record<string, unknown>[], TResult2 = never>(onfulfilled?: ((value: Record<string, unknown>[]) => TResult1 | PromiseLike<TResult1>) | null, onrejected?: ((reason: unknown) => TResult2 | PromiseLike<TResult2>) | null): Promise<TResult1 | TResult2>;
 }
+/** Fixed-table read-only grouped aggregates; no SQL, joins or table selection. */
+export interface DatabaseHostAggregation extends PromiseLike<Record<string, unknown>[]> {
+    min(field: string, alias?: string): DatabaseHostAggregation;
+    max(field: string, alias?: string): DatabaseHostAggregation;
+    groupBy(...fields: string[]): DatabaseHostAggregation;
+    where(query: Record<string, unknown>): DatabaseHostAggregation;
+}
 /**
  * select() 需要显式列名：'*' 在 SQL 方言里会被当成字面列名（no such column: "*"），
  * 类型层直接拒绝；运行时另有可读报错兜底（见 Host 实现）。
@@ -21,6 +28,8 @@ type SelectFields<Fields extends readonly string[]> = {
  * and the Host-backed `@zhin.js/database` adapter.
  */
 export interface DatabaseHostModel {
+    /** Optional SQL capability; lightweight and transaction models may omit it. */
+    aggregate?(): DatabaseHostAggregation;
     select<Fields extends string[]>(...fields: SelectFields<Fields>): DatabaseHostSelection;
     insert(row: Record<string, unknown>): Promise<unknown>;
     delete(): {

package/lib/database-host.js

@@ -99,8 +99,22 @@ export class PluginDatabaseHost extends OwnerScopedResourceHost {
         };
         return Object.freeze(chain);
     }
+    #bindAggregation(aggregation) {
+        const modify = (operation) => this.#operation.setup(() => {
+            const next = operation();
+            return next === aggregation ? chain : this.#bindAggregation(next);
+        });
+        const chain = {
+            min: (field, alias) => modify(() => aggregation.min(field, alias)),
+            max: (field, alias) => modify(() => aggregation.max(field, alias)),
+            groupBy: (...fields) => modify(() => aggregation.groupBy(...fields)),
+            where: query => modify(() => aggregation.where(query)),
+            then: (fulfilled, rejected) => this.#execute(() => Promise.resolve(aggregation)).then(fulfilled, rejected),
+        };
+        return Object.freeze(chain);
+    }
     #bindModel(model) {
-        const count = model.count?.bind(model);
+        const count = model.count?.bind(model), aggregate = model.aggregate?.bind(model);
         return Object.freeze({
             select: (...fields) => this.#operation.setup(() => this.#bindSelection(model.select(...fields))),
             insert: (row) => this.#execute(() => model.insert(row)),
@@ -111,6 +125,7 @@ export class PluginDatabaseHost extends OwnerScopedResourceHost {
                 where: (query) => this.#execute(() => model.update(patch).where(query)),
             })),
             ...(count ? { count: (query) => this.#execute(() => count(query)) } : {}),
+            ...(aggregate ? { aggregate: () => this.#operation.setup(() => this.#bindAggregation(aggregate())) } : {}),
         });
     }
     async #execute(operation) {
@@ -125,8 +140,16 @@ export function guardTransactionModel(model, check) {
         limit(count) { check(); return selection(source.limit(count)); },
         then(resolve, reject) { return Promise.resolve().then(() => { check(); return source; }).then(resolve, reject); },
     });
+    const aggregation = (source) => ({
+        min(field, alias) { check(); return aggregation(source.min(field, alias)); },
+        max(field, alias) { check(); return aggregation(source.max(field, alias)); },
+        groupBy(...fields) { check(); return aggregation(source.groupBy(...fields)); },
+        where(query) { check(); return aggregation(source.where(query)); },
+        then(resolve, reject) { return Promise.resolve().then(() => { check(); return source; }).then(resolve, reject); },
+    });
     return {
         select: (...fields) => { check(); return selection(model.select(...fields)); },
+        ...(model.aggregate ? { aggregate: () => { check(); return aggregation(model.aggregate()); } } : {}),
         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); } }; },

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.18",
+  "version": "1.1.20",
   "description": "Zero-dependency Plugin tree, Scope and atomic generation runtime for Zhin",
   "type": "module",
   "main": "./lib/index.js",