@zhin.js/adapter 1.1.11 → 1.2.0

package/README.md

@@ -26,8 +26,13 @@ AdapterIndex 和 generation lifecycle 管理。
 
 Adapter definitions declare `capabilities` for inbound/outbound admission and
 `operations` for optional actions such as `recall`, `edit`, `reaction`, and
-`typing`. Runtime callers should query the resulting `EndpointCapabilities`
-instead of probing optional endpoint methods. The zero-dependency types live in
+`typing`. `operations` accepts either a static list or a resolver receiving the
+concrete `AdapterContext`; use the resolver when connection modes expose different
+operations. `AdapterIndex` resolves, freezes, and exposes the exact set for every
+expanded Endpoint. Runtime callers should query the resulting `EndpointCapabilities`
+instead of probing optional endpoint methods. Declarations and the explicit
+`EndpointControl` port are validated in both directions, so hidden or unimplemented
+operations fail candidate generation before commit. The zero-dependency types live in
 [`@zhin.js/im-contract`](../im-contract/README.md).
 
 Framework-facing outbound code carries a structured `ConversationRef`.
@@ -45,7 +50,8 @@ boundary.
 
 New adapters should provide `control` directly and declare matching
 `operations`. Protocol-specific methods and compound string identifiers are not
-inspected or adapted by the runtime.
+inspected by the runtime. `createRecallEndpointControl()` bridges the common
+platform `recall(messageId)` shape without leaking that shape into Core.
 
 ## Endpoint 生命周期基座（createEndpointLifecycle）
 

package/lib/adapter-index.d.ts

@@ -1,14 +1,16 @@
 import { generationAdmissionSource, type CapabilityId, type CapabilitySlot, type GenerationAdmissionGate, type PluginId, type RuntimeSnapshot } from '@zhin.js/plugin-runtime';
-import type { AdapterCapability, AdapterDefinition, AdapterSegmentPolicy, EndpointInstance, EndpointSendRequest } from './definition.js';
+import { type AdapterCapability, type AdapterDefinition, type AdapterOperation, type AdapterSegmentPolicy, type EndpointInstance, type EndpointSendRequest } from './definition.js';
 import { type EndpointManagementCapability } from './endpoint-management.js';
+import { type EndpointControl } from './endpoint-control.js';
 import { type EndpointContentResolveContext } from './endpoint-content.js';
-import type { ConversationReference, ConversationResolution } from '@zhin.js/im-contract';
+import type { ConversationReference, ConversationResolution, EndpointCapabilities } from '@zhin.js/im-contract';
 export interface AdapterDescriptor {
     readonly id: CapabilityId;
     readonly owner: PluginId;
     readonly name: string;
     readonly source: string;
     readonly capabilities: readonly AdapterCapability[];
+    readonly operations: readonly AdapterOperation[];
 }
 /** Console / Host-facing endpoint row (connected = admission open). */
 export interface AdapterEndpointSummary extends AdapterDescriptor {
@@ -37,6 +39,10 @@ export declare class AdapterIndex {
      */
     instance(adapter: string, endpointKey: string): EndpointInstance | undefined;
     owner(id: CapabilityId): PluginId;
+    /** Exact, serializable capabilities for one concrete Endpoint. */
+    capabilities(id: CapabilityId): EndpointCapabilities;
+    /** Returns the control port only when the concrete Endpoint declared the operation and is active. */
+    control(id: CapabilityId, operation: AdapterOperation): EndpointControl | undefined;
     /**
      * Endpoint 的消息段能力声明（出站协商降级依据）；
      * 未声明或未知 id 返回 undefined（调用方按历史行为处理）。

package/lib/adapter-index.js

@@ -1,7 +1,8 @@
 import { DisposeStack, GenerationCompensationError, createGenerationAdmissionGate, generationAdmissionSource, } from '@zhin.js/plugin-runtime';
 import { createCapabilityContext } from '@zhin.js/feature-kit';
+import { endpointCapabilitiesOf, resolveAdapterOperations, } from './definition.js';
 import { listEndpointManagementCapabilities, } from './endpoint-management.js';
-import { assertDeclaredEndpointOperations } from './endpoint-control.js';
+import { assertDeclaredEndpointOperations, endpointControlOf, } from './endpoint-control.js';
 import { endpointContentOf } from './endpoint-content.js';
 export class AdapterIndex {
     $projection = 'zhin.adapter-index/1';
@@ -21,7 +22,7 @@ export class AdapterIndex {
             for (const slot of [...slots].sort((left, right) => left.id.localeCompare(right.id))) {
                 signal.throwIfAborted();
                 for (const expansion of expandEndpointConfigs(slot, snapshot)) {
-                    const endpoint = await createEndpoint(slot, snapshot, admission, signal, expansion);
+                    const created = await createEndpoint(slot, snapshot, admission, signal, expansion);
                     signal.throwIfAborted();
                     records.push({
                         id: expansion.id,
@@ -31,7 +32,8 @@ export class AdapterIndex {
                         name: expansion.endpointId,
                         source: slot.source,
                         capabilities: slot.definition.capabilities,
-                        endpoint,
+                        operations: created.operations,
+                        endpoint: created.endpoint,
                         ...(slot.definition.segments ? { segments: slot.definition.segments } : {}),
                         started: false,
                         open: false,
@@ -59,6 +61,7 @@ export class AdapterIndex {
             name: endpointLiveName(record.endpoint) ?? record.name,
             source: record.source,
             capabilities: record.capabilities,
+            operations: record.operations,
             connected: record.open && !record.stopped,
             status: record.open && !record.stopped ? 'online' : 'offline',
             phase: endpointPhase(record),
@@ -94,6 +97,22 @@ export class AdapterIndex {
             throw new Error(`Unknown Adapter Endpoint: ${id}`);
         return record.owner;
     }
+    /** Exact, serializable capabilities for one concrete Endpoint. */
+    capabilities(id) {
+        const record = this.#records.get(id);
+        if (!record)
+            throw new Error(`Unknown Adapter Endpoint: ${id}`);
+        return endpointCapabilitiesOf(record, record.operations);
+    }
+    /** Returns the control port only when the concrete Endpoint declared the operation and is active. */
+    control(id, operation) {
+        const record = this.#records.get(id);
+        if (!record || !record.started || record.stopped)
+            return undefined;
+        if (!record.operations.includes(operation))
+            return undefined;
+        return endpointControlOf(record.endpoint);
+    }
     /**
      * Endpoint 的消息段能力声明（出站协商降级依据）；
      * 未声明或未知 id 返回 undefined（调用方按历史行为处理）。
@@ -300,18 +319,20 @@ function expandEndpointConfigs(slot, snapshot) {
     })));
 }
 async function createEndpoint(slot, snapshot, admission, signal, expansion) {
-    const endpoint = await slot.definition.create(Object.freeze({
+    const context = Object.freeze({
         ...createCapabilityContext(snapshot, slot.owner, admission, signal),
         ...(expansion?.config ? { config: expansion.config } : {}),
         id: expansion?.id ?? slot.id,
         name: slot.localName,
-    }));
+    });
+    const operations = resolveAdapterOperations(slot.definition, context);
+    const endpoint = await slot.definition.create(context);
     assertEndpoint(endpoint, expansion?.id ?? slot.id);
     if (slot.definition.capabilities.includes('outbound') && typeof endpoint.send !== 'function') {
         throw new TypeError(`Adapter Endpoint ${String(expansion?.id ?? slot.id)} declares outbound but send() is missing`);
     }
-    assertDeclaredEndpointOperations(endpoint, slot.definition.operations, String(expansion?.id ?? slot.id));
-    return endpoint;
+    assertDeclaredEndpointOperations(endpoint, operations, String(expansion?.id ?? slot.id));
+    return Object.freeze({ endpoint, operations });
 }
 async function stopRecords(records, primaryError) {
     const stack = new DisposeStack();

package/lib/definition.d.ts

@@ -8,6 +8,8 @@ declare const adapterBrand: "zhin.adapter/1";
 export type AdapterCapability = 'inbound' | 'outbound';
 /** Operations beyond sending, declared by an Adapter definition. */
 export type AdapterOperation = Exclude<EndpointOperation, 'send'>;
+/** Resolve operations for one concrete Endpoint configuration. */
+export type AdapterOperationDeclaration<TConfig = unknown> = readonly AdapterOperation[] | ((context: AdapterContext<TConfig>) => readonly AdapterOperation[]);
 /** 端点可消费的出站媒体来源形式。 */
 export type AdapterOutboundMedia = 'url' | 'path' | 'base64' | 'upload';
 /** 交互段（卡片/按钮等富交互）的端点消费方式。 */
@@ -80,7 +82,7 @@ export interface AdapterDefinition<TConfig = unknown> {
      * `capabilities: ['outbound']`; a method existing on an endpoint is not a
      * capability declaration.
      */
-    readonly operations?: readonly AdapterOperation[];
+    readonly operations?: AdapterOperationDeclaration<TConfig>;
     /** 可选：端点消息段能力声明（出站协商降级挂载点）。 */
     readonly segments?: AdapterSegmentPolicy;
     create(context: AdapterContext<TConfig>): EndpointInstance | Promise<EndpointInstance>;
@@ -92,6 +94,8 @@ declare module '@zhin.js/plugin-runtime' {
 }
 export declare function defineAdapter<TConfig = unknown>(definition: Omit<AdapterDefinition<TConfig>, '$feature'>): Readonly<AdapterDefinition<TConfig>>;
 /** Converts the definition's compact authoring form into the public contract. */
-export declare function endpointCapabilitiesOf(definition: Pick<AdapterDefinition, 'capabilities' | 'operations'>): EndpointCapabilities;
+export declare function endpointCapabilitiesOf(definition: Pick<AdapterDefinition, 'capabilities' | 'operations'>, resolvedOperations?: readonly AdapterOperation[]): EndpointCapabilities;
+/** Resolve and validate the operation declaration for one concrete Endpoint. */
+export declare function resolveAdapterOperations<TConfig>(definition: Pick<AdapterDefinition<TConfig>, 'operations'>, context: AdapterContext<TConfig>): readonly AdapterOperation[];
 export declare function parseAdapterDefinition(value: unknown): AdapterDefinition;
 export {};

package/lib/definition.js

@@ -14,7 +14,9 @@ export function defineAdapter(definition) {
         throw new TypeError('Adapter capabilities must contain inbound and/or outbound');
     }
     const segments = normalizeSegmentPolicy(definition.segments);
-    const operations = normalizeOperations(definition.operations);
+    const operations = typeof definition.operations === 'function'
+        ? definition.operations
+        : normalizeOperations(definition.operations);
     return Object.freeze({
         ...definition,
         $feature: adapterBrand,
@@ -24,14 +26,27 @@ export function defineAdapter(definition) {
     });
 }
 /** Converts the definition's compact authoring form into the public contract. */
-export function endpointCapabilitiesOf(definition) {
-    const operations = definition.operations?.reduce((result, operation) => ({ ...result, [operation]: true }), {});
+export function endpointCapabilitiesOf(definition, resolvedOperations) {
+    if (typeof definition.operations === 'function' && resolvedOperations === undefined) {
+        throw new TypeError('Dynamic Adapter operations must be resolved for one Endpoint');
+    }
+    const declared = resolvedOperations
+        ?? (Array.isArray(definition.operations) ? definition.operations : undefined);
+    const operations = declared?.reduce((result, operation) => ({ ...result, [operation]: true }), {});
     return Object.freeze({
         inbound: definition.capabilities.includes('inbound'),
         outbound: definition.capabilities.includes('outbound'),
         ...(operations && Object.keys(operations).length > 0 ? { operations: Object.freeze(operations) } : {}),
     });
 }
+/** Resolve and validate the operation declaration for one concrete Endpoint. */
+export function resolveAdapterOperations(definition, context) {
+    const declaration = definition.operations;
+    const operations = typeof declaration === 'function'
+        ? declaration(context)
+        : declaration;
+    return normalizeOperations(operations) ?? Object.freeze([]);
+}
 function normalizeOperations(operations) {
     if (operations === undefined)
         return undefined;
@@ -93,7 +108,9 @@ export function parseAdapterDefinition(value) {
         throw invalidAdapter();
     // defineAdapter 已校验过形状；外部手工构造的 definition 也在此兜底
     normalizeSegmentPolicy(definition.segments);
-    normalizeOperations(definition.operations);
+    if (typeof definition.operations !== 'function') {
+        normalizeOperations(definition.operations);
+    }
     return definition;
 }
 function invalidAdapter() {

package/lib/endpoint-control.d.ts

@@ -19,9 +19,13 @@ export interface EndpointControl {
 export interface EndpointWithControl {
     readonly control?: EndpointControl;
 }
+/** Bridges the common platform `recall(messageId)` shape into canonical control. */
+export declare function createRecallEndpointControl(recallById: (messageId: string) => void | Promise<void>): Readonly<EndpointControl>;
 /** Reads the canonical control port without probing protocol-specific methods. */
 export declare function endpointControlOf(endpoint: unknown): EndpointControl | undefined;
 /** Checks only an Endpoint's explicit `control` port; protocol methods are never probed. */
 export declare function hasExplicitEndpointOperation(endpoint: unknown, operation: 'recall' | 'edit' | 'reaction' | 'typing'): boolean;
+/** Lists the semantic operations implemented by an Endpoint's explicit control port. */
+export declare function listExplicitEndpointOperations(endpoint: unknown): readonly ('recall' | 'edit' | 'reaction' | 'typing')[];
 /** Rejects a declaration that cannot be fulfilled by the explicit control port. */
 export declare function assertDeclaredEndpointOperations(endpoint: unknown, operations: readonly ('recall' | 'edit' | 'reaction' | 'typing')[] | undefined, id: string): void;

package/lib/endpoint-control.js

@@ -1,3 +1,9 @@
+/** Bridges the common platform `recall(messageId)` shape into canonical control. */
+export function createRecallEndpointControl(recallById) {
+    return Object.freeze({
+        recall: (message) => Promise.resolve(recallById(message.id)),
+    });
+}
 /** Reads the canonical control port without probing protocol-specific methods. */
 export function endpointControlOf(endpoint) {
     if (!endpoint || typeof endpoint !== 'object')
@@ -19,6 +25,25 @@ export function hasExplicitEndpointOperation(endpoint, operation) {
         case 'typing': return typeof control.typing === 'function';
     }
 }
+/** Lists the semantic operations implemented by an Endpoint's explicit control port. */
+export function listExplicitEndpointOperations(endpoint) {
+    if (!endpoint || typeof endpoint !== 'object')
+        return Object.freeze([]);
+    const control = endpoint.control;
+    if (!control || typeof control !== 'object')
+        return Object.freeze([]);
+    const operations = [];
+    if (typeof control.recall === 'function')
+        operations.push('recall');
+    if (typeof control.edit === 'function')
+        operations.push('edit');
+    if (typeof control.addReaction === 'function'
+        || typeof control.removeReaction === 'function')
+        operations.push('reaction');
+    if (typeof control.typing === 'function')
+        operations.push('typing');
+    return Object.freeze(operations);
+}
 /** Rejects a declaration that cannot be fulfilled by the explicit control port. */
 export function assertDeclaredEndpointOperations(endpoint, operations, id) {
     for (const operation of operations ?? []) {
@@ -26,7 +51,19 @@ export function assertDeclaredEndpointOperations(endpoint, operations, id) {
             throw new TypeError(`Adapter Endpoint ${id} declares ${operation} but control.${controlMethodName(operation)} is missing`);
         }
     }
+    const declared = new Set(operations ?? []);
+    for (const operation of listExplicitEndpointOperations(endpoint)) {
+        if (!declared.has(operation)) {
+            throw new TypeError(`Adapter Endpoint ${id} exposes control.${explicitControlMethodName(endpoint, operation)} but does not declare ${operation}`);
+        }
+    }
 }
 function controlMethodName(operation) {
     return operation === 'reaction' ? 'addReaction' : operation;
 }
+function explicitControlMethodName(endpoint, operation) {
+    if (operation !== 'reaction')
+        return operation;
+    const control = endpoint.control;
+    return typeof control?.addReaction === 'function' ? 'addReaction' : 'removeReaction';
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhin.js/adapter",
-  "version": "1.1.11",
+  "version": "1.2.0",
   "description": "Convention-based Adapter and Endpoint Feature for Zhin Plugin Runtime",
   "type": "module",
   "main": "./lib/index.js",
@@ -18,8 +18,8 @@
   ],
   "dependencies": {
     "yaml": "^2.9.0",
-    "@zhin.js/im-contract": "1.0.4",
     "@zhin.js/feature-kit": "1.0.12",
+    "@zhin.js/im-contract": "1.0.4",
     "@zhin.js/logger": "1.0.76",
     "@zhin.js/plugin-runtime": "1.1.7"
   },

package/src/adapter-index.ts

@@ -10,20 +10,31 @@ import {
   type RuntimeSnapshot,
 } from '@zhin.js/plugin-runtime';
 import { createCapabilityContext } from '@zhin.js/feature-kit';
-import type {
-  AdapterCapability,
-  AdapterDefinition,
-  AdapterSegmentPolicy,
-  EndpointInstance,
-  EndpointSendRequest,
+import {
+  endpointCapabilitiesOf,
+  resolveAdapterOperations,
+  type AdapterCapability,
+  type AdapterDefinition,
+  type AdapterOperation,
+  type AdapterSegmentPolicy,
+  type EndpointInstance,
+  type EndpointSendRequest,
 } from './definition.js';
 import {
   listEndpointManagementCapabilities,
   type EndpointManagementCapability,
 } from './endpoint-management.js';
-import { assertDeclaredEndpointOperations } from './endpoint-control.js';
+import {
+  assertDeclaredEndpointOperations,
+  endpointControlOf,
+  type EndpointControl,
+} from './endpoint-control.js';
 import { endpointContentOf, type EndpointContentResolveContext } from './endpoint-content.js';
-import type { ConversationReference, ConversationResolution } from '@zhin.js/im-contract';
+import type {
+  ConversationReference,
+  ConversationResolution,
+  EndpointCapabilities,
+} from '@zhin.js/im-contract';
 
 export interface AdapterDescriptor {
   readonly id: CapabilityId;
@@ -31,6 +42,7 @@ export interface AdapterDescriptor {
   readonly name: string;
   readonly source: string;
   readonly capabilities: readonly AdapterCapability[];
+  readonly operations: readonly AdapterOperation[];
 }
 
 /** Console / Host-facing endpoint row (connected = admission open). */
@@ -80,7 +92,7 @@ export class AdapterIndex {
       for (const slot of [...slots].sort((left, right) => left.id.localeCompare(right.id))) {
         signal.throwIfAborted();
         for (const expansion of expandEndpointConfigs(slot, snapshot)) {
-          const endpoint = await createEndpoint(slot, snapshot, admission, signal, expansion);
+          const created = await createEndpoint(slot, snapshot, admission, signal, expansion);
           signal.throwIfAborted();
           records.push({
             id: expansion.id,
@@ -90,7 +102,8 @@ export class AdapterIndex {
             name: expansion.endpointId,
             source: slot.source,
             capabilities: slot.definition.capabilities,
-            endpoint,
+            operations: created.operations,
+            endpoint: created.endpoint,
             ...(slot.definition.segments ? { segments: slot.definition.segments } : {}),
             started: false,
             open: false,
@@ -122,6 +135,7 @@ export class AdapterIndex {
       name: endpointLiveName(record.endpoint) ?? record.name,
       source: record.source,
       capabilities: record.capabilities,
+      operations: record.operations,
       connected: record.open && !record.stopped,
       status: record.open && !record.stopped ? 'online' as const : 'offline' as const,
       phase: endpointPhase(record),
@@ -158,6 +172,21 @@ export class AdapterIndex {
     return record.owner;
   }
 
+  /** Exact, serializable capabilities for one concrete Endpoint. */
+  capabilities(id: CapabilityId): EndpointCapabilities {
+    const record = this.#records.get(id);
+    if (!record) throw new Error(`Unknown Adapter Endpoint: ${id}`);
+    return endpointCapabilitiesOf(record, record.operations);
+  }
+
+  /** Returns the control port only when the concrete Endpoint declared the operation and is active. */
+  control(id: CapabilityId, operation: AdapterOperation): EndpointControl | undefined {
+    const record = this.#records.get(id);
+    if (!record || !record.started || record.stopped) return undefined;
+    if (!record.operations.includes(operation)) return undefined;
+    return endpointControlOf(record.endpoint);
+  }
+
   /**
    * Endpoint 的消息段能力声明（出站协商降级依据）；
    * 未声明或未知 id 返回 undefined（调用方按历史行为处理）。
@@ -396,15 +425,15 @@ async function createEndpoint(
   admission: GenerationAdmissionGate,
   signal: AbortSignal,
   expansion?: EndpointExpansion,
-): Promise<EndpointInstance> {
-  const endpoint = await slot.definition.create(
-    Object.freeze({
-      ...createCapabilityContext(snapshot, slot.owner, admission, signal),
-      ...(expansion?.config ? { config: expansion.config } : {}),
-      id: expansion?.id ?? slot.id,
-      name: slot.localName,
-    }),
-  );
+): Promise<Readonly<{ endpoint: EndpointInstance; operations: readonly AdapterOperation[] }>> {
+  const context = Object.freeze({
+    ...createCapabilityContext(snapshot, slot.owner, admission, signal),
+    ...(expansion?.config ? { config: expansion.config } : {}),
+    id: expansion?.id ?? slot.id,
+    name: slot.localName,
+  });
+  const operations = resolveAdapterOperations(slot.definition, context);
+  const endpoint = await slot.definition.create(context);
   assertEndpoint(endpoint, expansion?.id ?? slot.id);
   if (slot.definition.capabilities.includes('outbound') && typeof endpoint.send !== 'function') {
     throw new TypeError(
@@ -413,10 +442,10 @@ async function createEndpoint(
   }
   assertDeclaredEndpointOperations(
     endpoint,
-    slot.definition.operations,
+    operations,
     String(expansion?.id ?? slot.id),
   );
-  return endpoint;
+  return Object.freeze({ endpoint, operations });
 }
 
 async function stopRecords(

package/src/definition.ts

@@ -16,6 +16,11 @@ export type AdapterCapability = 'inbound' | 'outbound';
 /** Operations beyond sending, declared by an Adapter definition. */
 export type AdapterOperation = Exclude<EndpointOperation, 'send'>;
 
+/** Resolve operations for one concrete Endpoint configuration. */
+export type AdapterOperationDeclaration<TConfig = unknown> =
+  | readonly AdapterOperation[]
+  | ((context: AdapterContext<TConfig>) => readonly AdapterOperation[]);
+
 /** 端点可消费的出站媒体来源形式。 */
 export type AdapterOutboundMedia = 'url' | 'path' | 'base64' | 'upload';
 
@@ -103,7 +108,7 @@ export interface AdapterDefinition<TConfig = unknown> {
    * `capabilities: ['outbound']`; a method existing on an endpoint is not a
    * capability declaration.
    */
-  readonly operations?: readonly AdapterOperation[];
+  readonly operations?: AdapterOperationDeclaration<TConfig>;
   /** 可选：端点消息段能力声明（出站协商降级挂载点）。 */
   readonly segments?: AdapterSegmentPolicy;
   create(
@@ -134,7 +139,9 @@ export function defineAdapter<TConfig = unknown>(
     throw new TypeError('Adapter capabilities must contain inbound and/or outbound');
   }
   const segments = normalizeSegmentPolicy(definition.segments);
-  const operations = normalizeOperations(definition.operations);
+  const operations = typeof definition.operations === 'function'
+    ? definition.operations
+    : normalizeOperations(definition.operations);
   return Object.freeze({
     ...definition,
     $feature: adapterBrand,
@@ -147,8 +154,14 @@ export function defineAdapter<TConfig = unknown>(
 /** Converts the definition's compact authoring form into the public contract. */
 export function endpointCapabilitiesOf(
   definition: Pick<AdapterDefinition, 'capabilities' | 'operations'>,
+  resolvedOperations?: readonly AdapterOperation[],
 ): EndpointCapabilities {
-  const operations = definition.operations?.reduce<Partial<Record<AdapterOperation, true>>>(
+  if (typeof definition.operations === 'function' && resolvedOperations === undefined) {
+    throw new TypeError('Dynamic Adapter operations must be resolved for one Endpoint');
+  }
+  const declared = resolvedOperations
+    ?? (Array.isArray(definition.operations) ? definition.operations : undefined);
+  const operations = declared?.reduce<Partial<Record<AdapterOperation, true>>>(
     (result, operation) => ({ ...result, [operation]: true }),
     {},
   );
@@ -159,6 +172,18 @@ export function endpointCapabilitiesOf(
   });
 }
 
+/** Resolve and validate the operation declaration for one concrete Endpoint. */
+export function resolveAdapterOperations<TConfig>(
+  definition: Pick<AdapterDefinition<TConfig>, 'operations'>,
+  context: AdapterContext<TConfig>,
+): readonly AdapterOperation[] {
+  const declaration = definition.operations;
+  const operations = typeof declaration === 'function'
+    ? declaration(context)
+    : declaration;
+  return normalizeOperations(operations) ?? Object.freeze([]);
+}
+
 function normalizeOperations(
   operations: readonly AdapterOperation[] | undefined,
 ): readonly AdapterOperation[] | undefined {
@@ -240,7 +265,9 @@ export function parseAdapterDefinition(value: unknown): AdapterDefinition {
   ) throw invalidAdapter();
   // defineAdapter 已校验过形状；外部手工构造的 definition 也在此兜底
   normalizeSegmentPolicy(definition.segments);
-  normalizeOperations(definition.operations);
+  if (typeof definition.operations !== 'function') {
+    normalizeOperations(definition.operations);
+  }
   return definition as AdapterDefinition;
 }
 

package/src/endpoint-control.ts

@@ -23,6 +23,15 @@ export interface EndpointWithControl {
   readonly control?: EndpointControl;
 }
 
+/** Bridges the common platform `recall(messageId)` shape into canonical control. */
+export function createRecallEndpointControl(
+  recallById: (messageId: string) => void | Promise<void>,
+): Readonly<EndpointControl> {
+  return Object.freeze<EndpointControl>({
+    recall: (message) => Promise.resolve(recallById(message.id)),
+  });
+}
+
 /** Reads the canonical control port without probing protocol-specific methods. */
 export function endpointControlOf(endpoint: unknown): EndpointControl | undefined {
   if (!endpoint || typeof endpoint !== 'object') return undefined;
@@ -46,6 +55,24 @@ export function hasExplicitEndpointOperation(
   }
 }
 
+/** Lists the semantic operations implemented by an Endpoint's explicit control port. */
+export function listExplicitEndpointOperations(
+  endpoint: unknown,
+): readonly ('recall' | 'edit' | 'reaction' | 'typing')[] {
+  if (!endpoint || typeof endpoint !== 'object') return Object.freeze([]);
+  const control = (endpoint as EndpointWithControl).control;
+  if (!control || typeof control !== 'object') return Object.freeze([]);
+  const operations: Array<'recall' | 'edit' | 'reaction' | 'typing'> = [];
+  if (typeof control.recall === 'function') operations.push('recall');
+  if (typeof control.edit === 'function') operations.push('edit');
+  if (
+    typeof control.addReaction === 'function'
+    || typeof control.removeReaction === 'function'
+  ) operations.push('reaction');
+  if (typeof control.typing === 'function') operations.push('typing');
+  return Object.freeze(operations);
+}
+
 /** Rejects a declaration that cannot be fulfilled by the explicit control port. */
 export function assertDeclaredEndpointOperations(
   endpoint: unknown,
@@ -59,8 +86,25 @@ export function assertDeclaredEndpointOperations(
       );
     }
   }
+  const declared = new Set(operations ?? []);
+  for (const operation of listExplicitEndpointOperations(endpoint)) {
+    if (!declared.has(operation)) {
+      throw new TypeError(
+        `Adapter Endpoint ${id} exposes control.${explicitControlMethodName(endpoint, operation)} but does not declare ${operation}`,
+      );
+    }
+  }
 }
 
 function controlMethodName(operation: 'recall' | 'edit' | 'reaction' | 'typing'): string {
   return operation === 'reaction' ? 'addReaction' : operation;
 }
+
+function explicitControlMethodName(
+  endpoint: unknown,
+  operation: 'recall' | 'edit' | 'reaction' | 'typing',
+): string {
+  if (operation !== 'reaction') return operation;
+  const control = (endpoint as EndpointWithControl).control;
+  return typeof control?.addReaction === 'function' ? 'addReaction' : 'removeReaction';
+}