@zhin.js/adapter 1.1.5 → 1.1.8

package/README.md

@@ -2,7 +2,10 @@
 
 Zhin Plugin Runtime 的 Adapter Feature。它从插件或项目的 `adapters/**/*.ts` 发现
 `defineAdapter()` 定义，按 Plugin owner 投影 Endpoint，并把 start/open/close/stop 纳入同一
-generation handoff。
+generation lifecycle。候选 Endpoint 可完成连接 readiness，但入站由 `SnapshotStore`
+切换的 generation admission gate 阻断到 commit；旧 Endpoint 不会在 commit 前被关闭。
+已声明的 Endpoint 默认都是 required：`create()`、`start()` 或 `open()` 任一步失败都会
+销毁整组候选 Endpoint 并拒绝本次 generation，不存在 inert stub 或后台 late-open。
 
 ```ts
 import { defineAdapter } from '@zhin.js/adapter';
@@ -17,7 +20,7 @@ export default defineAdapter({
 `lib/provider.js`；开发时可通过 conditional export 读取源码。
 
 单文件插件可用 `setup({ addAdapter })` 注册 `defineAdapter(...)`；Endpoint 仍由同一个
-AdapterIndex 和 generation handoff 管理。
+AdapterIndex 和 generation lifecycle 管理。
 
 ## Transport Contract
 
@@ -39,9 +42,8 @@ adapter-specific method names and compound message ids stay at the protocol
 boundary.
 
 New adapters should provide `control` directly and declare matching
-`operations`. During the 4.x migration, `resolveEndpointControl()` can adapt
-legacy `recallMessage` / `$recallMessage` / reaction methods, but that bridge
-exists only in this package and is not a public extension pattern.
+`operations`. Protocol-specific methods and compound string identifiers are not
+inspected or adapted by the runtime.
 
 ## Endpoint 生命周期基座（createEndpointLifecycle）
 

package/lib/adapter-index.d.ts

@@ -1,4 +1,4 @@
-import { type CapabilityId, type CapabilitySlot, type PluginId, type RuntimeSnapshot } from '@zhin.js/plugin-runtime';
+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 EndpointManagementCapability } from './endpoint-management.js';
 export interface AdapterDescriptor {
@@ -15,15 +15,13 @@ export interface AdapterEndpointSummary extends AdapterDescriptor {
     readonly phase: AdapterEndpointPhase;
     readonly managementCapabilities: readonly EndpointManagementCapability[];
 }
-export type AdapterEndpointPhase = 'pending' | 'starting' | 'online' | 'failed' | 'unconfigured';
+export type AdapterEndpointPhase = 'pending' | 'starting' | 'online';
 export declare class AdapterIndex {
     #private;
     readonly $projection: "zhin.adapter-index/1";
+    readonly [generationAdmissionSource]: readonly GenerationAdmissionGate[];
     private constructor();
-    static create(slots: readonly Readonly<CapabilitySlot<AdapterDefinition>>[], snapshot: RuntimeSnapshot, options?: {
-        readonly startTimeoutMs?: number;
-        readonly deferredGiveUpMs?: number;
-    }): Promise<AdapterIndex>;
+    static create(slots: readonly Readonly<CapabilitySlot<AdapterDefinition>>[], snapshot: RuntimeSnapshot, signal: AbortSignal): Promise<AdapterIndex>;
     list(): readonly AdapterDescriptor[];
     /** Endpoint rows for Console `endpoint.list` / `endpoint.info`. */
     describe(): readonly AdapterEndpointSummary[];
@@ -31,18 +29,20 @@ export declare class AdapterIndex {
      * Resolve a Console `$adapter` + `$endpoint` pair to a capability id.
      * Matches local name, capability id, or owner path segments.
      */
-    resolve(adapter: string, endpointId: string): CapabilityId | undefined;
+    resolve(adapter: string, endpointKey: string): CapabilityId | undefined;
     /**
      * Resolve a live EndpointInstance for Host-side side channels (reactions, etc.).
      */
-    instance(adapter: string, endpointId: string): EndpointInstance | undefined;
+    instance(adapter: string, endpointKey: string): EndpointInstance | undefined;
     owner(id: CapabilityId): PluginId;
     /**
      * Endpoint 的消息段能力声明（出站协商降级依据）；
      * 未声明或未知 id 返回 undefined（调用方按历史行为处理）。
      */
     segmentPolicy(id: CapabilityId): AdapterSegmentPolicy | undefined;
-    start(): Promise<void>;
+    start(signal?: AbortSignal): Promise<void>;
+    /** Required readiness boundary: no generation can publish a partial Endpoint set. */
+    activate(signal: AbortSignal): Promise<void>;
     open(): void;
     close(): Promise<void>;
     stop(): Promise<void>;

package/lib/adapter-index.js

@@ -1,62 +1,45 @@
-import { DisposeStack, } from '@zhin.js/plugin-runtime';
+import { DisposeStack, GenerationCompensationError, createGenerationAdmissionGate, generationAdmissionSource, } from '@zhin.js/plugin-runtime';
 import { createCapabilityContext } from '@zhin.js/feature-kit';
-import { formatCompact, getLogger } from '@zhin.js/logger';
 import { listEndpointManagementCapabilities, } from './endpoint-management.js';
 import { assertDeclaredEndpointOperations } from './endpoint-control.js';
-const logger = getLogger('Adapter');
 export class AdapterIndex {
     $projection = 'zhin.adapter-index/1';
     #records = new Map();
+    [generationAdmissionSource];
     #order;
-    /** True after `open()` until `close()` / `stop()` — late starts may open themselves. */
-    #admissionOpen = false;
-    #startTimeoutMs;
-    /** Final give-up budget for deferred starts (never-settling start promises). */
-    #deferredGiveUpMs;
-    constructor(records, startTimeoutMs, deferredGiveUpMs) {
+    constructor(records, admission) {
         this.#order = Object.freeze([...records]);
-        this.#startTimeoutMs = startTimeoutMs;
-        this.#deferredGiveUpMs = deferredGiveUpMs;
+        this[generationAdmissionSource] = Object.freeze([admission]);
         for (const record of records)
             this.#records.set(record.id, record);
     }
-    static async create(slots, snapshot, options = {}) {
+    static async create(slots, snapshot, signal) {
         const records = [];
-        const unconfigured = [];
+        const admission = createGenerationAdmissionGate();
         try {
             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 createEndpointSoft(slot, snapshot, expansion);
-                    if (endpoint.unconfigured)
-                        unconfigured.push(expansion.name);
+                    const endpoint = await createEndpoint(slot, snapshot, admission, signal, expansion);
+                    signal.throwIfAborted();
                     records.push({
                         id: expansion.id,
                         owner: slot.owner,
-                        // 展开模式下 record name 即 endpoint 名（entry.name），
-                        // 保证 Console 展示与 resolve/instance 按 entry name 命中唯一 record
-                        name: expansion.name,
+                        // 展开模式下 record name 即 endpoint id（entry.id），
+                        // 保证 Console 展示与 resolve/instance 按 entry id 命中唯一 record
+                        name: expansion.endpointId,
                         source: slot.source,
                         capabilities: slot.definition.capabilities,
-                        endpoint: endpoint.instance,
+                        endpoint,
                         ...(slot.definition.segments ? { segments: slot.definition.segments } : {}),
-                        unconfigured: endpoint.unconfigured,
                         started: false,
                         open: false,
-                        failed: false,
                         startAttempted: false,
-                        // Unconfigured stubs skip start/open so kitchen-sink Roots stay quiet.
-                        stopped: endpoint.unconfigured,
+                        stopped: false,
                     });
                 }
             }
-            if (unconfigured.length > 0) {
-                logger.info(formatCompact({
-                    op: 'adapters_unconfigured',
-                    count: unconfigured.length,
-                    names: unconfigured.join(','),
-                }));
-            }
-            return new AdapterIndex(records, options.startTimeoutMs ?? 3_000, options.deferredGiveUpMs ?? 60_000);
+            return new AdapterIndex(records, admission);
         }
         catch (error) {
             await stopRecords(records, error);
@@ -64,7 +47,7 @@ export class AdapterIndex {
         }
     }
     list() {
-        return this.#order.map(({ endpoint: _endpoint, unconfigured: _unconfigured, started: _started, open: _open, stopped: _stopped, failed: _failed, startAttempted: _startAttempted, segments: _segments, ...descriptor }) => Object.freeze(descriptor));
+        return this.#order.map(({ endpoint: _endpoint, started: _started, open: _open, stopped: _stopped, stopping: _stopping, startAttempted: _startAttempted, segments: _segments, ...descriptor }) => Object.freeze(descriptor));
     }
     /** Endpoint rows for Console `endpoint.list` / `endpoint.info`. */
     describe() {
@@ -85,21 +68,21 @@ export class AdapterIndex {
      * Resolve a Console `$adapter` + `$endpoint` pair to a capability id.
      * Matches local name, capability id, or owner path segments.
      */
-    resolve(adapter, endpointId) {
-        const matches = this.#order.filter((record) => matchesEndpoint(record, adapter, endpointId));
+    resolve(adapter, endpointKey) {
+        const matches = this.#order.filter((record) => matchesEndpoint(record, adapter, endpointKey));
         if (matches.length === 1)
             return matches[0]?.id;
         if (matches.length === 0)
             return undefined;
-        // Prefer exact localName === endpointId when ambiguous.
-        const exact = matches.find((record) => record.name === endpointId);
+        // Prefer exact localName === endpointKey when ambiguous.
+        const exact = matches.find((record) => record.name === endpointKey);
         return exact?.id ?? matches[0]?.id;
     }
     /**
      * Resolve a live EndpointInstance for Host-side side channels (reactions, etc.).
      */
-    instance(adapter, endpointId) {
-        const id = this.resolve(adapter, endpointId);
+    instance(adapter, endpointKey) {
+        const id = this.resolve(adapter, endpointKey);
         if (!id)
             return undefined;
         return this.#records.get(id)?.endpoint;
@@ -117,102 +100,55 @@ export class AdapterIndex {
     segmentPolicy(id) {
         return this.#records.get(id)?.segments;
     }
-    async start() {
-        // Soft-start in parallel with a short wait so kitchen-sink Roots do not
-        // stall generation. Configured platforms that need longer (QQ auth, Slack
-        // socket, GitHub verify) stay in-flight instead of being stop()'d mid-connect.
-        const startTimeoutMs = this.#startTimeoutMs;
-        await Promise.all(this.#order.map(async (record) => {
-            if (record.started || record.stopped)
-                return;
-            record.startAttempted = true;
-            const startPromise = (async () => record.endpoint.start?.())();
-            try {
-                await withTimeout(startPromise, startTimeoutMs, `Adapter start timed out after ${startTimeoutMs}ms`);
+    async start(signal = new AbortController().signal) {
+        try {
+            // Sequential readiness gives the candidate one owned in-flight start at a
+            // time. A sibling failure can therefore never leave an un-awaited start
+            // promise mutating resources after rollback has returned.
+            for (const record of this.#order) {
+                if (record.started || record.stopped)
+                    continue;
+                record.startAttempted = true;
+                signal.throwIfAborted();
+                let stopOnAbort;
+                const aborted = new Promise((_resolve, reject) => {
+                    stopOnAbort = () => {
+                        void stopRecord(record).then(() => reject(signal.reason ?? new Error('Adapter Endpoint start aborted')), (cleanupError) => reject(new GenerationCompensationError([signal.reason, cleanupError], 'Adapter Endpoint cancellation cleanup failed', { cause: cleanupError })));
+                    };
+                });
+                signal.addEventListener('abort', stopOnAbort, { once: true });
+                try {
+                    await Promise.race([
+                        Promise.resolve(record.endpoint.start?.(signal)),
+                        aborted,
+                    ]);
+                }
+                finally {
+                    signal.removeEventListener('abort', stopOnAbort);
+                }
+                signal.throwIfAborted();
                 if (record.stopped)
-                    return;
+                    throw new Error(`Adapter Endpoint stopped during start: ${record.id}`);
                 record.started = true;
             }
-            catch (error) {
-                const message = error instanceof Error ? error.message : String(error);
-                if (message.includes('timed out after')) {
-                    logger.info(formatCompact({
-                        op: 'adapter_start_deferred',
-                        id: record.id,
-                        name: record.name,
-                        waitMs: startTimeoutMs,
-                    }));
-                    // Final backstop: a deferred start promise that never settles must
-                    // not keep the Endpoint in limbo forever.
-                    const giveUp = setTimeout(() => {
-                        if (record.stopped || record.started)
-                            return;
-                        record.stopped = true;
-                        record.failed = true;
-                        // Swallow a late rejection so it does not become unhandled.
-                        void startPromise.catch(() => undefined);
-                        logger.warn(formatCompact({
-                            op: 'adapter_start_give_up',
-                            id: record.id,
-                            name: record.name,
-                            waitMs: this.#deferredGiveUpMs,
-                        }));
-                    }, this.#deferredGiveUpMs);
-                    giveUp.unref?.();
-                    void startPromise.then(() => {
-                        clearTimeout(giveUp);
-                        if (record.stopped || record.started)
-                            return;
-                        record.started = true;
-                        if (this.#admissionOpen && !record.open) {
-                            try {
-                                record.endpoint.open?.();
-                                record.open = true;
-                            }
-                            catch (openError) {
-                                logger.warn(formatCompact({
-                                    op: 'adapter_open_after_deferred_fail',
-                                    id: record.id,
-                                    name: record.name,
-                                    error: openError instanceof Error ? openError.message : String(openError),
-                                }));
-                            }
-                        }
-                    }, (startError) => {
-                        clearTimeout(giveUp);
-                        if (record.stopped)
-                            return;
-                        record.stopped = true;
-                        record.failed = true;
-                        logger.warn(formatCompact({
-                            op: 'adapter_start_soft_fail',
-                            id: record.id,
-                            name: record.name,
-                            error: startError instanceof Error ? startError.message : String(startError),
-                            stack: startError instanceof Error ? startError.stack : undefined,
-                        }));
-                    });
-                    return;
-                }
-                record.stopped = true;
-                record.failed = true;
-                void startPromise.catch(() => undefined);
-                // Startup connect failures are logged once here (with stack); Endpoint
-                // implementations must NOT re-log them at error level.
-                logger.warn(formatCompact({
-                    op: 'adapter_start_soft_fail',
-                    id: record.id,
-                    name: record.name,
-                    error: message,
-                    stack: error instanceof Error ? error.stack : undefined,
-                }));
-                // No endpoint.stop() here: adapter Endpoints self-stop in their start()
-                // catch by convention (verified across icqq/qq/slack/… endpoints).
-            }
-        }));
+        }
+        catch (error) {
+            await stopRecords(this.#order, error);
+            throw error;
+        }
+    }
+    /** Required readiness boundary: no generation can publish a partial Endpoint set. */
+    async activate(signal) {
+        try {
+            await this.start(signal);
+            this.open();
+        }
+        catch (error) {
+            await stopRecords(this.#order, error);
+            throw error;
+        }
     }
     open() {
-        this.#admissionOpen = true;
         const errors = [];
         for (const record of this.#order) {
             if (!record.started || record.open || record.stopped)
@@ -229,7 +165,6 @@ export class AdapterIndex {
             throw new AggregateError(errors, 'Adapter Endpoint open failed');
     }
     async close() {
-        this.#admissionOpen = false;
         const stack = new DisposeStack();
         for (const record of this.#order) {
             if (!record.open || record.stopped)
@@ -266,7 +201,7 @@ export function isAdapterIndex(value) {
     return !!value && typeof value === 'object'
         && value.$projection === 'zhin.adapter-index/1';
 }
-function matchesEndpoint(record, adapter, endpointId) {
+function matchesEndpoint(record, adapter, endpointKey) {
     // 消息上的 $adapter 是 CapabilityId 的 localName 段（多 endpoint 展开后形如
     // `icqq~8596238`）。CapabilityId 段分隔符是 \0（owner\0feature\0localName），
     // 不能用 `/` 去 endsWith，否则永远匹配不上（endpoint not found）。
@@ -281,10 +216,10 @@ function matchesEndpoint(record, adapter, endpointId) {
     // activity-feedback resolve with that id; slot.localName alone is not enough
     // when multiple plugin instances share localName "icqq".
     const liveName = endpointLiveName(record.endpoint);
-    const endpointOk = record.name === endpointId
-        || record.id === endpointId
-        || record.id.endsWith(`/${endpointId}`)
-        || (liveName !== undefined && liveName === endpointId);
+    const endpointOk = record.name === endpointKey
+        || record.id === endpointKey
+        || record.id.endsWith(`/${endpointKey}`)
+        || (liveName !== undefined && liveName === endpointKey);
     return adapterOk && endpointOk;
 }
 function endpointLiveName(endpoint) {
@@ -292,13 +227,9 @@ function endpointLiveName(endpoint) {
     return typeof name === 'string' && name.length > 0 ? name : undefined;
 }
 function endpointPhase(record) {
-    if (record.unconfigured)
-        return 'unconfigured';
-    if (record.failed)
-        return 'failed';
     if (record.open && !record.stopped)
         return 'online';
-    if (record.startAttempted)
+    if (record.startAttempted && !record.started)
         return 'starting';
     return 'pending';
 }
@@ -308,152 +239,89 @@ function assertEndpoint(value, id) {
     }
 }
 /**
- * Adapter `resolveXxxConfig` helpers report missing config/credentials as
- * TypeError("… requires …") by convention; only those are expected failures.
- */
-function isUnconfiguredError(error) {
-    return (error instanceof TypeError
-        && /requires|not configured|missing|未配置|缺少/i.test(error.message));
-}
-/**
- * 实例配置的 endpoint 展开：插件实例 config 含非空 `endpoints: [{name, ...覆盖}]` 时
+ * 实例配置的 endpoint 展开：插件实例 config 含非空 `endpoints: [{id, ...覆盖}]` 时
  * 按数组一一创建 endpoint（基础配置为实例 config 去掉 `endpoints` 键，逐项合并），
  * 否则按实例 config 创建单个 endpoint（历史行为）。
  */
 function expandEndpointConfigs(slot, snapshot) {
     const config = snapshot.config.get(slot.owner);
     const raw = config?.endpoints;
-    const entries = Array.isArray(raw)
-        ? raw.filter((entry) => !!entry && typeof entry === 'object'
-            && typeof entry.name === 'string'
-            && entry.name.length > 0)
-        : [];
+    if (raw !== undefined && !Array.isArray(raw)) {
+        throw new TypeError(`Adapter ${slot.id} endpoints must be an array`);
+    }
+    const entries = (raw ?? []);
     if (entries.length === 0) {
-        if (Array.isArray(raw) && raw.length > 0) {
-            logger.warn(formatCompact({
-                op: 'adapter_endpoints_entries_dropped',
-                id: slot.id,
-                reason: 'every endpoints entry is missing a non-empty string name',
-            }));
-        }
-        return Object.freeze([{ id: slot.id, name: slot.localName }]);
+        return Object.freeze([{ id: slot.id, endpointId: slot.localName }]);
     }
-    // `~` 是 record id 的分隔符、\0 是 CapabilityId 的分隔符，混入会破坏解析
-    const valid = entries.filter((entry) => {
-        if (/[~\0]/u.test(entry.name)) {
-            logger.warn(formatCompact({
-                op: 'adapter_endpoint_name_invalid',
-                id: slot.id,
-                name: entry.name,
-            }));
-            return false;
+    const normalized = entries.map((entry, index) => {
+        if (!entry || typeof entry !== 'object'
+            || typeof entry.id !== 'string'
+            || entry.id.length === 0) {
+            throw new TypeError(`Adapter ${slot.id} endpoints[${index}].id must be a non-empty string`);
         }
-        return true;
+        return entry;
     });
-    // 重名会让 #records 覆盖与 #order/resolve 三者不一致；保留首个并告警
+    // `~` 是 record id 的分隔符、\0 是 CapabilityId 的分隔符，混入会破坏解析。
+    for (const entry of normalized) {
+        if (/[~\0]/u.test(entry.id)) {
+            throw new TypeError(`Adapter ${slot.id} endpoint id contains a reserved delimiter: ${entry.id}`);
+        }
+    }
     const seen = new Set();
-    const deduped = valid.filter((entry) => {
-        if (seen.has(entry.name)) {
-            logger.warn(formatCompact({
-                op: 'adapter_endpoint_name_duplicate',
-                id: slot.id,
-                name: entry.name,
-            }));
-            return false;
+    for (const entry of normalized) {
+        if (seen.has(entry.id)) {
+            throw new TypeError(`Adapter ${slot.id} endpoint id is duplicated: ${entry.id}`);
         }
-        seen.add(entry.name);
-        return true;
-    });
-    if (deduped.length === 0) {
-        return Object.freeze([{ id: slot.id, name: slot.localName }]);
+        seen.add(entry.id);
     }
     const { endpoints: _drop, ...base } = (config ?? {});
-    return Object.freeze(deduped.map((entry) => Object.freeze({
-        id: `${slot.id}~${entry.name}`,
-        name: entry.name,
-        config: Object.freeze({ ...base, ...entry, name: entry.name }),
+    return Object.freeze(normalized.map((entry) => Object.freeze({
+        id: `${slot.id}~${entry.id}`,
+        endpointId: entry.id,
+        config: Object.freeze({ ...base, ...entry, id: entry.id }),
     })));
 }
-async function createEndpointSoft(slot, snapshot, expansion) {
-    let endpoint;
-    try {
-        endpoint = await slot.definition.create(Object.freeze({
-            ...createCapabilityContext(snapshot, slot.owner),
-            ...(expansion?.config ? { config: expansion.config } : {}),
-            id: expansion?.id ?? slot.id,
-            name: slot.localName,
-        }));
-    }
-    catch (error) {
-        // Missing config / credentials: degrade to an inert stub so the rest of
-        // the generation still boots. Anything else (network failures, bugs in
-        // create()) is unexpected — keep the stub but surface a warning instead
-        // of silently swallowing it at debug level.
-        const message = error instanceof Error ? error.message : String(error);
-        const log = isUnconfiguredError(error) ? logger.debug.bind(logger) : logger.warn.bind(logger);
-        log(formatCompact({
-            op: 'adapter_create_soft_fail',
-            id: expansion?.id ?? slot.id,
-            name: expansion?.name ?? slot.localName,
-            error: message,
-        }));
-        return {
-            instance: createUnconfiguredEndpoint(message),
-            unconfigured: true,
-        };
-    }
-    // Programming errors (create() did not return an Endpoint) must surface:
-    // they propagate to AdapterIndex.create's catch, which disposes the records
-    // created so far instead of hiding the bug behind an unconfigured stub.
+async function createEndpoint(slot, snapshot, admission, signal, expansion) {
+    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,
+    }));
     assertEndpoint(endpoint, expansion?.id ?? slot.id);
     assertDeclaredEndpointOperations(endpoint, slot.definition.operations, String(expansion?.id ?? slot.id));
-    return { instance: endpoint, unconfigured: false };
-}
-function createUnconfiguredEndpoint(reason) {
-    return Object.freeze({
-        start() {
-            throw new Error(`Adapter unconfigured: ${reason}`);
-        },
-        open() { },
-        close() { },
-        stop() { },
-        send() {
-            throw new Error(`Adapter unconfigured: ${reason}`);
-        },
-    });
-}
-function withTimeout(promise, ms, message) {
-    if (promise === undefined)
-        return Promise.resolve(undefined);
-    return new Promise((resolve, reject) => {
-        const timer = setTimeout(() => reject(new Error(message)), ms);
-        Promise.resolve(promise).then((value) => {
-            clearTimeout(timer);
-            resolve(value);
-        }, (error) => {
-            clearTimeout(timer);
-            reject(error);
-        });
-    });
+    return endpoint;
 }
 async function stopRecords(records, primaryError) {
     const stack = new DisposeStack();
     for (const record of records) {
         if (record.stopped)
             continue;
-        stack.add(async () => {
-            record.stopped = true;
-            record.open = false;
-            await record.endpoint.stop?.();
-        });
+        stack.add(() => stopRecord(record));
     }
     try {
         await stack.dispose();
     }
     catch (stopError) {
         if (primaryError !== undefined) {
-            throw new AggregateError([primaryError, stopError], 'Adapter prepare and Endpoint cleanup both failed', { cause: stopError });
+            throw new GenerationCompensationError([primaryError, stopError], 'Adapter prepare and Endpoint cleanup both failed', { cause: stopError });
         }
         throw stopError;
     }
 }
+function stopRecord(record) {
+    if (record.stopped)
+        return Promise.resolve();
+    if (record.stopping)
+        return record.stopping;
+    const stopping = Promise.resolve(record.endpoint.stop?.()).then(() => {
+        record.stopped = true;
+        record.open = false;
+    });
+    record.stopping = stopping;
+    void stopping.catch(() => undefined).finally(() => {
+        if (!record.stopped && record.stopping === stopping)
+            record.stopping = undefined;
+    });
+    return stopping;
+}

package/lib/definition.d.ts

@@ -21,9 +21,9 @@ export interface EndpointInstance<TResult = unknown> {
     readonly management?: EndpointManagement;
     /** Optional platform-neutral control surface for existing messages. */
     readonly control?: EndpointControl;
-    /** Allocates transport resources but must not admit inbound events yet. */
-    start?(): void | Promise<void>;
-    /** Opens admission after the candidate generation has committed. */
+    /** 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>;