@zhin.js/adapter 1.2.0 → 1.2.2

package/lib/endpoint-lifecycle.js

@@ -22,25 +22,19 @@
  *    构造器里 `this.#lifecycle = createEndpointLifecycle({ name: config.id, reconnect, heartbeat })`。
  * 2. `start()` 改为：
  *    ```ts
- *    this.#unregisterAgent = registerXxxAgentEndpoint(name, this); // agent 注册仍在适配器侧
- *    try {
- *      await this.#lifecycle.start(async (handle) => {
- *        this.#handle = handle; // 供 ws 'close' 回调引用
- *        await new Promise<void>((resolve, reject) => {
- *          const ws = createWebSocket(...); this.#ws = ws;
- *          ws.on('open', () => { this.#lifecycle.startHeartbeat(() => beat(), interval); resolve(); });
- *          ws.on('close', (code, reason) => { handle.notifyClosed(...); rejectIfNotSettled(...); });
- *          ws.on('error', (err) => rejectIfNotSettled(err));
- *        });
+ *    await this.#lifecycle.start(async (handle) => {
+ *      this.#handle = handle; // 供 ws 'close' 回调引用
+ *      await new Promise<void>((resolve, reject) => {
+ *        const ws = createWebSocket(...); this.#ws = ws;
+ *        ws.on('open', () => { this.#lifecycle.startHeartbeat(() => beat(), interval); resolve(); });
+ *        ws.on('close', (code, reason) => { handle.notifyClosed(...); rejectIfNotSettled(...); });
+ *        ws.on('error', (err) => rejectIfNotSettled(err));
  *      });
- *    } catch (err) {
- *      this.#unregisterAgent?.(); this.#unregisterAgent = undefined; // 反注册对称
- *      throw err;
- *    }
+ *    });
  *    ```
- *    start 失败复位由基座保证；agent 注册/反注册是适配器专有依赖，刻意不收入基座。
+ *    start 失败复位由基座保证；Client 由 Endpoint 直接持有，不建立旁路 registry。
  * 3. `stop()` 改为：先 `await this.#lifecycle.stop()`（清定时器 + 强关 ws + 竞态 settle），
- *    再做适配器专有清理（rejectAllPending、deduper.clear、agent 反注册）。
+ *    再做适配器专有清理（rejectAllPending、deduper.clear）。
  * 4. `handle.onForceClose(() => this.#ws?.close())` 在每次拿到新 socket 后注册，
  *    供心跳看门狗主动断开；ws 'message'/'pong' 回调里调 `notifyHeartbeatAck()` 喂狗。
  * 5. 退避参数由配置映射：reconnect_interval → initialIntervalMs，可按需覆盖
@@ -108,19 +102,20 @@ class EndpointLifecycleImpl {
         this.#connect = connect;
         this.#state = 'connecting';
         this.#attempt = 0;
+        const generation = this.#generation + 1;
         try {
             await this.#runConnect(connect);
         }
         catch (err) {
             // 注意：stop() 可能在 await 期间并发改写 #state，必须经 getter 读取避免 TS 窄化误判
-            if (this.#currentState() === 'stopped')
-                return; // stop-during-connect 竞态：静默 settle
+            if (generation !== this.#generation || this.#currentState() === 'stopped')
+                return;
             // start 失败复位：回 idle、不武装重连，允许调用方重试
             this.#state = 'idle';
             throw err;
         }
-        if (this.#currentState() === 'stopped')
-            return; // stop 竞态先于 open
+        if (generation !== this.#generation || this.#currentState() === 'stopped')
+            return;
         this.#state = 'open';
     }
     async stop() {
@@ -226,8 +221,18 @@ class EndpointLifecycleImpl {
                 this.#scheduleReconnect();
             },
             onForceClose: (close) => {
-                if (generation === this.#generation)
-                    this.#forceClose = close;
+                if (generation !== this.#generation)
+                    return;
+                if (this.#state === 'stopped') {
+                    try {
+                        close();
+                    }
+                    catch {
+                        /* same best-effort cleanup as stop() */
+                    }
+                    return;
+                }
+                this.#forceClose = close;
             },
         };
     }
@@ -237,7 +242,11 @@ class EndpointLifecycleImpl {
         this.#forceClose = undefined;
         const handle = this.#createHandle(generation);
         // Promise.resolve().then 兜底同步抛错；额外 catch 防止 stop 竞态后迟到拒绝变 unhandled
-        const connecting = Promise.resolve().then(() => connect(handle));
+        const connecting = Promise.resolve().then(() => {
+            if (generation !== this.#generation || this.#state === 'stopped')
+                return;
+            return connect(handle);
+        });
         connecting.catch(() => { });
         let wake;
         const stopped = new Promise((resolve) => {
@@ -291,11 +300,12 @@ class EndpointLifecycleImpl {
             const elapsed = await this.#sleep(delay);
             if (!elapsed || this.#currentState() !== 'reconnecting')
                 return;
+            const generation = this.#generation + 1;
             try {
                 await this.#runConnect(connect);
             }
             catch (err) {
-                if (this.#currentState() === 'stopped')
+                if (generation !== this.#generation || this.#currentState() === 'stopped')
                     return;
                 this.#attempt += 1;
                 logger.debug(formatCompact({
@@ -307,7 +317,7 @@ class EndpointLifecycleImpl {
                 }));
                 continue;
             }
-            if (this.#currentState() === 'stopped')
+            if (generation !== this.#generation || this.#currentState() === 'stopped')
                 return;
             this.#state = 'open';
             this.#attempt = 0;

package/lib/endpoint.d.ts

@@ -0,0 +1,78 @@
+import { type CapabilityId, type GenerationAdmissionGate } from '@zhin.js/plugin-runtime';
+import type { AdapterContext, EndpointSendRequest } from './definition.js';
+import type { EndpointManagement } from './endpoint-management.js';
+import type { EndpointControl } from './endpoint-control.js';
+import type { EndpointContentPort } from './endpoint-content.js';
+/** The one inbound event boundary shared by every platform Endpoint. */
+export interface EndpointEventGateway {
+    receive(event: EndpointEvent): Promise<unknown>;
+}
+/** Callback shape used by protocol normalizers which feed Endpoint.emit(). */
+export type EndpointEventEmitter = <TPayload>(name: string, payload: TPayload) => Promise<unknown>;
+/** Generation-bound gateway injected into Endpoint by AdapterIndex. */
+export declare const endpointEventGatewayToken: import("@zhin.js/plugin-runtime").Token<EndpointEventGateway>;
+/** Stable identity of the Endpoint which produced an event. */
+export interface EndpointIdentity {
+    readonly id: CapabilityId;
+    readonly adapter: string;
+}
+/**
+ * The single event context delivered from an Endpoint into Core and plugins.
+ * `client` is the actual platform SDK/protocol client owned by the Endpoint.
+ */
+export interface EndpointEvent<TPayload = unknown, TClient = unknown, TName extends string = string> {
+    readonly name: TName;
+    readonly payload: TPayload;
+    readonly endpoint: EndpointIdentity;
+    readonly client: TClient;
+}
+/** Lossless native event delivered before any optional canonical projection. */
+export interface PlatformEvent<TEvent = unknown, TName extends string = string> {
+    /** Native SDK/protocol event name, for example `guild_member_add`. */
+    readonly name: TName;
+    /** Native SDK/protocol payload without canonicalization. */
+    readonly event: TEvent;
+}
+declare const endpointBrand: unique symbol;
+declare const endpointBind: unique symbol;
+/**
+ * Deep platform boundary.
+ *
+ * Platform implementations inherit this class, expose the platform-native
+ * `client`, own account/transport lifecycle, and normalize every inbound SDK
+ * callback through `emit()`. Core owns dispatch, admission and plugin context.
+ */
+export declare abstract class Endpoint<TClient = unknown> {
+    #private;
+    readonly [endpointBrand] = true;
+    /**
+     * Platform SDK or protocol client exposed to plugin code.
+     * It must be a distinct object: Endpoint owns framework lifecycle, Client
+     * owns platform operations.
+     */
+    abstract readonly client: TClient;
+    readonly management?: EndpointManagement;
+    readonly control?: EndpointControl;
+    readonly content?: EndpointContentPort;
+    /** @internal Bound exactly once by the generation-owned AdapterIndex. */
+    [endpointBind](context: AdapterContext, admission?: GenerationAdmissionGate): void;
+    /** The identity is available after AdapterDefinition.create returns. */
+    get identity(): EndpointIdentity;
+    /** The only legal platform-to-framework event ingress. */
+    protected emit<TPayload, TName extends string>(name: TName, payload: TPayload): Promise<unknown>;
+    /**
+     * Lossless native-event projection. Adapters call this before deriving
+     * message/notice/request/system events, including for unknown event kinds.
+     */
+    protected emitPlatform<TEvent, TName extends string>(name: TName, event: TEvent): Promise<unknown>;
+    abstract start(signal: AbortSignal): void | Promise<void>;
+    abstract open(): void;
+    abstract close(): void | Promise<void>;
+    abstract stop(): void | Promise<void>;
+    send?(_request: EndpointSendRequest): string | Promise<string>;
+}
+/** @internal AdapterIndex binding hook; deliberately not exported by name. */
+export declare function bindEndpoint(endpoint: Endpoint, context: AdapterContext, admission?: GenerationAdmissionGate): void;
+/** @internal Cross-generation Endpoint check that survives ESM module re-evaluation. */
+export declare function isEndpoint(value: unknown): value is Endpoint;
+export {};

package/lib/endpoint.js

@@ -0,0 +1,100 @@
+import { createToken, } from '@zhin.js/plugin-runtime';
+/** Generation-bound gateway injected into Endpoint by AdapterIndex. */
+export const endpointEventGatewayToken = createToken('zhin.adapter.endpoint-events');
+const endpointBrand = Symbol.for('zhin.adapter.endpoint/1');
+const endpointBind = Symbol.for('zhin.adapter.endpoint-bind/1');
+const PRE_ADMISSION_EVENT_LIMIT = 256;
+/**
+ * Deep platform boundary.
+ *
+ * Platform implementations inherit this class, expose the platform-native
+ * `client`, own account/transport lifecycle, and normalize every inbound SDK
+ * callback through `emit()`. Core owns dispatch, admission and plugin context.
+ */
+export class Endpoint {
+    [endpointBrand] = true;
+    management;
+    control;
+    content;
+    #identity;
+    #events;
+    #admissionState = 'unbound';
+    #pendingEvents = [];
+    /** @internal Bound exactly once by the generation-owned AdapterIndex. */
+    [endpointBind](context, admission) {
+        if (this.#events)
+            throw new Error(`Endpoint ${context.id} is already bound`);
+        this.#identity = Object.freeze({ id: context.id, adapter: context.name });
+        this.#events = context.use(endpointEventGatewayToken);
+        if (!admission) {
+            this.#admissionState = 'active';
+            return;
+        }
+        this.#admissionState = 'pending';
+        admission.onActivate(() => {
+            if (this.#admissionState !== 'pending')
+                return;
+            this.#admissionState = 'active';
+            admission.onDeactivate(() => {
+                this.#admissionState = 'retired';
+                this.#pendingEvents.length = 0;
+            });
+            const pending = this.#pendingEvents.splice(0);
+            for (const event of pending) {
+                void this.#events?.receive(event).catch(() => undefined);
+            }
+        });
+    }
+    /** The identity is available after AdapterDefinition.create returns. */
+    get identity() {
+        if (!this.#identity)
+            throw new Error('Endpoint is not bound to a runtime generation');
+        return this.#identity;
+    }
+    /** The only legal platform-to-framework event ingress. */
+    emit(name, payload) {
+        if (!this.#events || !this.#identity) {
+            throw new Error('Endpoint emitted before it was bound to a runtime generation');
+        }
+        const event = Object.freeze({
+            name,
+            payload,
+            endpoint: this.#identity,
+            client: this.client,
+        });
+        if (this.#admissionState === 'pending') {
+            if (this.#pendingEvents.length >= PRE_ADMISSION_EVENT_LIMIT) {
+                this.#pendingEvents.shift();
+            }
+            this.#pendingEvents.push(event);
+            return Promise.resolve(undefined);
+        }
+        if (this.#admissionState === 'retired')
+            return Promise.resolve(undefined);
+        return this.#events.receive(event);
+    }
+    /**
+     * Lossless native-event projection. Adapters call this before deriving
+     * message/notice/request/system events, including for unknown event kinds.
+     */
+    emitPlatform(name, event) {
+        return this.emit('platform.receive', Object.freeze({ name, event }));
+    }
+}
+/** @internal AdapterIndex binding hook; deliberately not exported by name. */
+export function bindEndpoint(endpoint, context, admission) {
+    endpoint[endpointBind](context, admission);
+}
+/** @internal Cross-generation Endpoint check that survives ESM module re-evaluation. */
+export function isEndpoint(value) {
+    if (!value || typeof value !== 'object')
+        return false;
+    const candidate = value;
+    return candidate[endpointBrand] === true
+        && typeof candidate[endpointBind] === 'function'
+        && typeof candidate.start === 'function'
+        && typeof candidate.open === 'function'
+        && typeof candidate.close === 'function'
+        && typeof candidate.stop === 'function'
+        && 'client' in candidate;
+}

package/lib/index.d.ts

@@ -1,12 +1,18 @@
+/**
+ * Adapter authoring contracts and platform-neutral Endpoint capabilities.
+ * @module @zhin.js/adapter
+ */
 /** @internal 适配器 projection（AdapterIndex），框架内部机制，不承诺不 break。 */
 export * from './adapter-index.js';
 export * from './credentials.js';
 /** @public 用户侧创作面：`defineAdapter`（`adapters/` 约定目录默认导出，承诺 semver）。 */
 export * from './definition.js';
+export * from './endpoint.js';
 export * from './endpoint-commands.js';
 export * from './endpoint-lifecycle.js';
 export * from './endpoint-management.js';
 export * from './endpoint-control.js';
 export * from './endpoint-content.js';
+export * from './endpoint-client.js';
 export * from './provider.js';
 export { default } from './provider.js';

package/lib/index.js

@@ -1,12 +1,18 @@
+/**
+ * Adapter authoring contracts and platform-neutral Endpoint capabilities.
+ * @module @zhin.js/adapter
+ */
 /** @internal 适配器 projection（AdapterIndex），框架内部机制，不承诺不 break。 */
 export * from './adapter-index.js';
 export * from './credentials.js';
 /** @public 用户侧创作面：`defineAdapter`（`adapters/` 约定目录默认导出，承诺 semver）。 */
 export * from './definition.js';
+export * from './endpoint.js';
 export * from './endpoint-commands.js';
 export * from './endpoint-lifecycle.js';
 export * from './endpoint-management.js';
 export * from './endpoint-control.js';
 export * from './endpoint-content.js';
+export * from './endpoint-client.js';
 export * from './provider.js';
 export { default } from './provider.js';

package/lib/provider.d.ts

@@ -1,5 +1,5 @@
 import { AdapterIndex } from './adapter-index.js';
 export declare const adapterFeatureId: import("@zhin.js/plugin-runtime").FeatureId;
-declare const adapterFeature: Readonly<import("@zhin.js/feature-kit").FeatureProvider<import("./definition.js").AdapterDefinition<unknown>, AdapterIndex>>;
+declare const adapterFeature: Readonly<import("@zhin.js/feature-kit").FeatureProvider<import("./definition.js").AdapterDefinition<unknown, unknown>, AdapterIndex>>;
 export { adapterFeature };
 export default adapterFeature;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhin.js/adapter",
-  "version": "1.2.0",
+  "version": "1.2.2",
   "description": "Convention-based Adapter and Endpoint Feature for Zhin Plugin Runtime",
   "type": "module",
   "main": "./lib/index.js",
@@ -18,15 +18,15 @@
   ],
   "dependencies": {
     "yaml": "^2.9.0",
-    "@zhin.js/feature-kit": "1.0.12",
+    "@zhin.js/feature-kit": "1.0.13",
     "@zhin.js/im-contract": "1.0.4",
-    "@zhin.js/logger": "1.0.76",
-    "@zhin.js/plugin-runtime": "1.1.7"
+    "@zhin.js/logger": "1.0.77",
+    "@zhin.js/plugin-runtime": "1.1.8"
   },
   "devDependencies": {
     "@types/node": "^26.1.2",
     "typescript": "^6.0.3",
-    "@zhin.js/command": "1.0.15"
+    "@zhin.js/command": "1.0.16"
   },
   "zhin": {
     "protocol": 1,

package/src/adapter-index.ts

@@ -17,9 +17,9 @@ import {
   type AdapterDefinition,
   type AdapterOperation,
   type AdapterSegmentPolicy,
-  type EndpointInstance,
   type EndpointSendRequest,
 } from './definition.js';
+import { bindEndpoint, isEndpoint, type Endpoint } from './endpoint.js';
 import {
   listEndpointManagementCapabilities,
   type EndpointManagementCapability,
@@ -57,7 +57,7 @@ export type AdapterEndpointPhase =
   'pending' | 'starting' | 'online';
 
 interface AdapterRecord extends AdapterDescriptor {
-  readonly endpoint: EndpointInstance;
+  readonly endpoint: Endpoint;
   readonly segments?: AdapterSegmentPolicy;
   started: boolean;
   open: boolean;
@@ -157,15 +157,49 @@ export class AdapterIndex {
     return exact?.id ?? matches[0]?.id;
   }
 
-  /**
-   * Resolve a live EndpointInstance for Host-side side channels (reactions, etc.).
-   */
-  instance(adapter: string, endpointKey: string): EndpointInstance | undefined {
+  /** Resolve the framework-owned Endpoint for internal Host control ports. */
+  connection(adapter: string, endpointKey: string): Endpoint | undefined {
     const id = this.resolve(adapter, endpointKey);
     if (!id) return undefined;
     return this.#records.get(id)?.endpoint;
   }
 
+  /** Resolve the platform-native client owned by one active Endpoint. */
+  client<TClient>(adapter: string, endpointKey: string): TClient {
+    const id = this.resolve(adapter, endpointKey);
+    const record = id ? this.#records.get(id) : undefined;
+    if (!record) throw new Error(`Endpoint ${adapter}/${endpointKey} does not exist`);
+    if (!record.started || record.stopped) {
+      throw new Error(`Endpoint ${adapter}/${endpointKey} is not active`);
+    }
+    return record.endpoint.client as TClient;
+  }
+
+  /** Resolve the Client directly from a generation-stable CapabilityId. */
+  clientById<TClient>(id: CapabilityId): TClient {
+    const record = this.#records.get(id);
+    if (!record) throw new Error(`Unknown Adapter Endpoint: ${id}`);
+    if (!record.started || record.stopped) {
+      throw new Error(`Adapter Endpoint ${id} is not active`);
+    }
+    return record.endpoint.client as TClient;
+  }
+
+  /** Literal adapter name used by authoring-context type discrimination. */
+  clientAdapter(id: CapabilityId): string {
+    const record = this.#records.get(id);
+    if (!record) throw new Error(`Unknown Adapter Endpoint: ${id}`);
+    return record.endpoint.identity.adapter;
+  }
+
+  /** Optional Client lookup for cross-platform middleware and routing. */
+  findClient<TClient>(adapter: string, endpointKey: string): TClient | undefined {
+    const id = this.resolve(adapter, endpointKey);
+    const record = id ? this.#records.get(id) : undefined;
+    if (!record || !record.started || record.stopped) return undefined;
+    return record.endpoint.client as TClient;
+  }
+
   owner(id: CapabilityId): PluginId {
     const record = this.#records.get(id);
     if (!record) throw new Error(`Unknown Adapter Endpoint: ${id}`);
@@ -228,6 +262,11 @@ export class AdapterIndex {
         }
         signal.throwIfAborted();
         if (record.stopped) throw new Error(`Adapter Endpoint stopped during start: ${record.id}`);
+        if (record.endpoint.client === record.endpoint) {
+          throw new TypeError(
+            `Adapter Endpoint ${record.id} must expose a distinct platform client`,
+          );
+        }
         record.started = true;
       }
     } catch (error) {
@@ -335,7 +374,7 @@ function matchesEndpoint(
     || record.id.endsWith(`/${adapter}`)
     || record.owner === adapter
     || record.owner.endsWith(`/${adapter}`);
-  // Live EndpointInstance.name is the bot runtime id (e.g. ICQQ uin). Host /
+  // The live Endpoint identity is the bot runtime id (e.g. ICQQ uin). Host /
   // activity-feedback resolve with that id; slot.localName alone is not enough
   // when multiple plugin instances share localName "icqq".
   const liveName = endpointLiveName(record.endpoint);
@@ -346,7 +385,7 @@ function matchesEndpoint(
   return adapterOk && endpointOk;
 }
 
-function endpointLiveName(endpoint: EndpointInstance): string | undefined {
+function endpointLiveName(endpoint: Endpoint): string | undefined {
   const name = (endpoint as { readonly name?: unknown }).name;
   return typeof name === 'string' && name.length > 0 ? name : undefined;
 }
@@ -357,9 +396,9 @@ function endpointPhase(record: AdapterRecord): AdapterEndpointPhase {
   return 'pending';
 }
 
-function assertEndpoint(value: unknown, id: CapabilityId): asserts value is EndpointInstance {
-  if (!value || typeof value !== 'object') {
-    throw new TypeError(`Adapter ${id} create() must return an Endpoint instance`);
+function assertEndpoint(value: unknown, id: CapabilityId): asserts value is Endpoint {
+  if (!isEndpoint(value)) {
+    throw new TypeError(`Adapter ${id} create() must return an Endpoint subclass`);
   }
 }
 
@@ -425,7 +464,7 @@ async function createEndpoint(
   admission: GenerationAdmissionGate,
   signal: AbortSignal,
   expansion?: EndpointExpansion,
-): Promise<Readonly<{ endpoint: EndpointInstance; operations: readonly AdapterOperation[] }>> {
+): Promise<Readonly<{ endpoint: Endpoint; operations: readonly AdapterOperation[] }>> {
   const context = Object.freeze({
     ...createCapabilityContext(snapshot, slot.owner, admission, signal),
     ...(expansion?.config ? { config: expansion.config } : {}),
@@ -435,6 +474,7 @@ async function createEndpoint(
   const operations = resolveAdapterOperations(slot.definition, context);
   const endpoint = await slot.definition.create(context);
   assertEndpoint(endpoint, expansion?.id ?? slot.id);
+  bindEndpoint(endpoint, context, admission);
   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`,

package/src/definition.ts

@@ -1,3 +1,7 @@
+/**
+ * Adapter authoring API consumed from `zhin.js/adapter`.
+ * @module zhin.js/adapter
+ */
 import type { CapabilityId } from '@zhin.js/plugin-runtime';
 import type { CapabilityContext } from '@zhin.js/feature-kit';
 import type {
@@ -5,9 +9,19 @@ import type {
   EndpointCapabilities,
   EndpointOperation,
 } from '@zhin.js/im-contract';
-import type { EndpointManagement } from './endpoint-management.js';
-import type { EndpointControl } from './endpoint-control.js';
-import type { EndpointContentPort } from './endpoint-content.js';
+import type { Endpoint } from './endpoint.js';
+
+export { Endpoint } from './endpoint.js';
+export type {
+  EndpointEvent,
+  EndpointIdentity,
+  PlatformEvent,
+} from './endpoint.js';
+export { defineEndpointClient } from './endpoint-client.js';
+export type {
+  EndpointClientContext,
+  EndpointClientToken,
+} from './endpoint-client.js';
 
 const adapterBrand = 'zhin.adapter/1' as const;
 
@@ -35,25 +49,9 @@ export interface EndpointSendRequest {
   readonly payload: unknown;
 }
 
-export interface EndpointInstance {
-  /** Optional platform-neutral Console/Host management surface. */
-  readonly management?: EndpointManagement;
-  /** Optional platform-neutral control surface for existing messages. */
-  readonly control?: EndpointControl;
-  /** Optional canonical resolver for message, merged-forward and media references. */
-  readonly content?: EndpointContentPort;
-  /** Required readiness; must observe abort and settle before rollback returns. */
-  start?(signal: AbortSignal): void | Promise<void>;
-  /** Opens Endpoint-local flow behind the candidate generation admission gate. */
-  open?(): void;
-  /** Stops new inbound events while preserving in-flight work. */
-  close?(): void | Promise<void>;
-  /** Releases transport resources. Calls must be idempotent. */
-  stop?(): void | Promise<void>;
-  /** Platform message id. Core wraps it in the canonical MessageRef/DeliveryReceipt. */
-  send?(request: EndpointSendRequest): string | Promise<string>;
-}
-
+/**
+ * Generation-owned construction context for one runtime Endpoint.
+ */
 export interface AdapterContext<TConfig = unknown> extends CapabilityContext<TConfig> {
   readonly id: CapabilityId;
   readonly name: string;
@@ -100,7 +98,8 @@ const OUTBOUND_MEDIA_FORMS: readonly AdapterOutboundMedia[] = [
 
 const ADAPTER_OPERATIONS: readonly AdapterOperation[] = ['recall', 'edit', 'reaction', 'typing'];
 
-export interface AdapterDefinition<TConfig = unknown> {
+export interface AdapterDefinition<TConfig = unknown, TClient = unknown> {
+  /** @internal Runtime feature brand. */
   readonly $feature: typeof adapterBrand;
   readonly capabilities: readonly AdapterCapability[];
   /**
@@ -113,7 +112,7 @@ export interface AdapterDefinition<TConfig = unknown> {
   readonly segments?: AdapterSegmentPolicy;
   create(
     context: AdapterContext<TConfig>,
-  ): EndpointInstance | Promise<EndpointInstance>;
+  ): Endpoint<TClient> | Promise<Endpoint<TClient>>;
 }
 
 declare module '@zhin.js/plugin-runtime' {
@@ -125,6 +124,23 @@ declare module '@zhin.js/plugin-runtime' {
   }
 }
 
+/**
+ * Define an Adapter module for the `adapters/` convention directory.
+ *
+ * The returned definition is immutable and declares capabilities before an
+ * Endpoint is created, so Runtime admission can fail closed.
+ *
+ * @public
+ * @example
+ * ```ts
+ * import { defineAdapter } from 'zhin.js/adapter';
+ *
+ * export default defineAdapter({
+ *   capabilities: ['inbound', 'outbound'],
+ *   create: () => new MyPlatformEndpoint(),
+ * });
+ * ```
+ */
 export function defineAdapter<TConfig = unknown>(
   definition: Omit<AdapterDefinition<TConfig>, '$feature'>,
 ): Readonly<AdapterDefinition<TConfig>> {
@@ -151,7 +167,10 @@ export function defineAdapter<TConfig = unknown>(
   });
 }
 
-/** Converts the definition's compact authoring form into the public contract. */
+/**
+ * Converts the definition's compact authoring form into the Runtime contract.
+ * @internal Adapter projection helper.
+ */
 export function endpointCapabilitiesOf(
   definition: Pick<AdapterDefinition, 'capabilities' | 'operations'>,
   resolvedOperations?: readonly AdapterOperation[],
@@ -172,7 +191,10 @@ export function endpointCapabilitiesOf(
   });
 }
 
-/** Resolve and validate the operation declaration for one concrete Endpoint. */
+/**
+ * Resolve and validate the operation declaration for one concrete Endpoint.
+ * @internal Adapter projection helper.
+ */
 export function resolveAdapterOperations<TConfig>(
   definition: Pick<AdapterDefinition<TConfig>, 'operations'>,
   context: AdapterContext<TConfig>,
@@ -251,6 +273,7 @@ function normalizeSegmentPolicy(
   });
 }
 
+/** @internal Runtime validation for convention-discovered modules. */
 export function parseAdapterDefinition(value: unknown): AdapterDefinition {
   if (!value || typeof value !== 'object') throw invalidAdapter();
   const definition = value as Partial<AdapterDefinition>;