@oxidezap/baileyrs 0.0.35 → 0.1.0

package/README.md

@@ -25,7 +25,7 @@ so existing integrations can migrate with minimal changes. See
 | Media encrypt/decrypt | Node.js crypto | Rust AES-256-CBC + HMAC |
 | Media upload/download | JS fetch + temp files | Rust with CDN failover, auth refresh, resumable upload |
 | Key management | JS auth state | Rust `PersistenceManager` |
-| Auto-reconnect | Manual `startSock()` loop | Built-in with fibonacci backoff |
+| Auto-reconnect | Manual `startSock()` loop | Transient drops retried in Rust (fibonacci backoff); terminal ones still yours |
 
 ## Documentation
 
@@ -51,9 +51,16 @@ import makeWASocket from '@oxidezap/baileyrs'
 ### Drop-in replacement for upstream Baileys
 
 baileyrs is API-compatible with [@whiskeysockets/baileys](https://github.com/WhiskeySockets/Baileys).
-Existing projects switch over by aliasing the package — **no source changes needed**
-(one exception: carrying an existing pairing across takes a one-line import swap,
-see [Migrating from Upstream Baileys](#migrating-from-upstream-baileys)):
+Existing projects switch over by aliasing the package — **the API and imports
+need no source changes**. Two things do:
+
+- Carrying an existing pairing across takes a one-line import swap, see
+  [Migrating from Upstream Baileys](#migrating-from-upstream-baileys).
+- If your `connection.update` handler was written for a version of baileyrs
+  before 0.1, see [Gotchas](#gotchas): a `close` now always means the socket
+  is finished, and you have to recreate it. Code written against upstream
+  Baileys already does the right thing.
+
 
 ```sh
 npm install @whiskeysockets/baileys@npm:@oxidezap/baileyrs
@@ -78,27 +85,57 @@ now resolves to baileyrs.
 import makeWASocket, { Boom, DisconnectReason, useMultiFileAuthState } from '@oxidezap/baileyrs'
 
 const { state } = await useMultiFileAuthState('auth_info')
-const sock = makeWASocket({ auth: state })
 
-sock.ev.on('connection.update', ({ connection, lastDisconnect }) => {
-    if (connection === 'close') {
-        const statusCode = (lastDisconnect?.error as Boom)?.output?.statusCode
-        if (statusCode === DisconnectReason.loggedOut) {
-            console.log('Logged out')
-        }
-        // Auto-reconnect is handled by the Rust engine — no need to call makeWASocket again
+// setTimeout caps at ~2^31-1 ms (~24.8 days) and fires immediately past that,
+// so a long ban has to be waited out in chunks.
+async function waitUntil(deadlineMs: number) {
+    for (let left = deadlineMs - Date.now(); left > 0; left = deadlineMs - Date.now()) {
+        await new Promise(resolve => setTimeout(resolve, Math.min(left, 2_147_483_647)))
     }
-    if (connection === 'open') {
-        console.log('Connected')
-    }
-})
+}
 
-sock.ev.on('messages.upsert', ({ messages }) => {
-    for (const msg of messages) {
-        console.log('received message', msg.key.id)
-    }
-})
+async function connectToWhatsApp() {
+    const sock = makeWASocket({ auth: state })
+
+    sock.ev.on('connection.update', ({ connection, lastDisconnect }) => {
+        if (connection === 'close') {
+            // `close` means this socket is finished — same as upstream Baileys.
+            // Transient drops never get here; the Rust engine retries those and
+            // reports `connecting`.
+            const statusCode = (lastDisconnect?.error as Boom)?.output?.statusCode
+            // See the reconnect table under Gotchas: a few terminal closes
+            // reject the replacement just as fast, so they are not worth
+            // retrying — or not yet. `Example/example.ts` has the full policy.
+            if (statusCode === DisconnectReason.loggedOut || statusCode === 405) {
+                console.log('Closed for good', statusCode)
+            } else if (statusCode === DisconnectReason.forbidden) {
+                // Temporary ban: `expire` is unix seconds. A missing or past
+                // expiry means the ban is over — reconnect like any other
+                // terminal close rather than staying offline forever.
+                const expire = (lastDisconnect?.error as Boom)?.data?.expire
+                console.log('Temporarily banned until', expire)
+                waitUntil(typeof expire === 'number' ? expire * 1000 : 0).then(connectToWhatsApp)
+            } else {
+                setTimeout(connectToWhatsApp, 5_000)
+            }
+        }
+        if (connection === 'open') {
+            console.log('Connected')
+        }
+    })
+
+    // Register every handler in here. A replacement socket is a new emitter,
+    // so anything attached outside stops firing after the first reconnect.
+    sock.ev.on('messages.upsert', ({ messages }) => {
+        for (const msg of messages) {
+            console.log('received message', msg.key.id)
+        }
+    })
+
+    return sock
+}
 
+const sock = await connectToWhatsApp()
 await sock.sendMessage('1234567890@s.whatsapp.net', { text: 'Hello!' })
 ```
 
@@ -156,9 +193,25 @@ preserved. No QR re-scan, no logged-out events.
 
 A few behaviors that differ from upstream — almost always to your advantage:
 
-- **Auto-reconnect is built in.** Don't call `makeWASocket()` again from
-  `connection.update`'s `'close'` branch. The Rust engine retries with
-  fibonacci backoff; opening a second socket leaks the first one.
+- **Auto-reconnect is built in, but `close` still means `close`.** The Rust
+  engine retries transient drops on a fibonacci backoff and reports them as
+  `connection: 'connecting'`, so the canonical upstream handler never fires
+  for those and you never end up with two sockets on one account. A
+  `connection: 'close'` is only emitted once the engine has given up — a
+  replaced session, an outdated build, a temporary ban, an unrecoverable
+  `<failure>` — and by then the socket has already released its resources.
+  Ignoring it leaves the bot permanently offline, so handle it the upstream
+  way and build a replacement — with three exceptions, because some of those
+  failures reject the replacement just as fast:
+
+  | `statusCode` | what to do |
+  | --- | --- |
+  | `DisconnectReason.loggedOut` (401) | stop; needs a fresh pairing |
+  | `405` | stop; the server rejected this build, and the next one too |
+  | `DisconnectReason.forbidden` (403) | wait until `lastDisconnect.error.data.expire` (unix seconds) — it is a temporary ban |
+  | anything else | reconnect, after a short delay |
+
+  `Example/example.ts` implements exactly this.
 - **No `getMessage` / `cachedGroupMetadata` polyfill required.** The Rust
   side caches group metadata and message keys natively. You can still pass
   them — they're respected as overrides — but they're optional.

package/lib/Compatibility/proto-runtime.js

@@ -558,34 +558,44 @@ class ProtoCompatibilityRuntime {
         const reader = new LongBinaryReader(asUint8Array(input));
         return this.hydrate(schemaId, codec.decode(reader, length));
     }
+    /**
+     * A fresh instance rather than an in-place re-parent: the codec installs its
+     * own `toJSON` on what it returns, and deleting that normalizes the object
+     * into dictionary mode, where every later read is a megamorphic lookup.
+     */
     hydrate(schemaId, value) {
-        const object = isObject(value) ? value : {};
+        const source = isObject(value) ? value : {};
+        const instance = Object.create(this.constructorFor(schemaId).prototype);
         const messageFields = this.messageFieldsByName[schemaId];
-        for (const key in object) {
+        for (const key in source) {
+            const nested = source[key];
             const field = messageFields[key];
-            if (!field)
-                continue;
-            const nested = object[key];
-            if (field[3] & PROTO_FIELD_FLAG.repeated) {
-                if (Array.isArray(nested))
-                    for (const item of nested)
-                        if (isObject(item))
-                            this.hydrate(field[2], item);
+            if (!field) {
+                instance[key] = nested;
             }
-            else if (field[3] & PROTO_FIELD_FLAG.map) {
-                if (isObject(nested))
-                    for (const item of Object.values(nested))
+            else if (field[3] & PROTO_FIELD_FLAG.repeated) {
+                if (Array.isArray(nested)) {
+                    for (let index = 0; index < nested.length; index++) {
+                        const item = nested[index];
                         if (isObject(item))
-                            this.hydrate(field[2], item);
+                            nested[index] = this.hydrate(field[2], item);
+                    }
+                }
+                instance[key] = nested;
             }
-            else if (isObject(nested)) {
-                this.hydrate(field[2], nested);
+            else if (field[3] & PROTO_FIELD_FLAG.map && isObject(nested)) {
+                const entries = {};
+                for (const entry in nested) {
+                    const item = nested[entry];
+                    entries[entry] = isObject(item) ? this.hydrate(field[2], item) : item;
+                }
+                instance[key] = entries;
+            }
+            else {
+                instance[key] = isObject(nested) ? this.hydrate(field[2], nested) : nested;
             }
         }
-        if (hasOwn(object, 'toJSON'))
-            delete object.toJSON;
-        Object.setPrototypeOf(object, this.constructorFor(schemaId).prototype);
-        return object;
+        return instance;
     }
     projectForEncode(schemaId, value) {
         if (!isObject(value))

package/lib/Compatibility/websocket-client.d.ts

@@ -12,8 +12,13 @@ export declare class WebSocketClient extends EventEmitter {
     protected readonly socket: {
         readonly readyState: ReadyState;
     };
-    private closing;
-    private closed;
+    /**
+     * One value rather than a pair of booleans plus a promise that could
+     * disagree with them. `closing` carries the in-flight close so a second
+     * caller joins it instead of returning while the first `disconnect()` is
+     * still running — which is how teardown reached `free()` on a busy client.
+     */
+    private closeState;
     private readonly getClient;
     private listenerMutationDepth;
     constructor(url: string | URL, config: SocketConfig, getClient: () => WasmWhatsAppClient | undefined);
@@ -32,6 +37,22 @@ export declare class WebSocketClient extends EventEmitter {
     off(eventName: string | symbol, listener: EventListener): this;
     removeAllListeners(eventName?: string | symbol): this;
     connect(): void;
+    /**
+     * Idempotent, and a second caller joins the first rather than returning
+     * while it is still going.
+     *
+     * The early return used to be bare: `void ws.close(); await sock.end()` saw
+     * the flag, returned immediately, and let teardown reach `free()` with the
+     * original `disconnect()` still in flight — the wasm heap corruption
+     * `bridge-free-safety.test.ts` documents. Awaiting a *second* `disconnect()`
+     * does not join the first one.
+     *
+     * The state is stored before `disconnect()` is called, and the work is
+     * deferred by a microtask to make that ordering hold: an inline async body
+     * runs eagerly to its first `await`, so `disconnect()` would be invoked
+     * while the state still said `open`, and anything it reaches synchronously
+     * that calls back into `close()` would issue a second one.
+     */
     close(): Promise<void>;
     send(str: string | Uint8Array, cb?: (err?: Error) => void): boolean;
     private get readyState();

package/lib/Compatibility/websocket-client.js

@@ -7,8 +7,13 @@ export const isRawNodeForwardingEnabled = (client) => client.hasRawNodeListeners
 export class WebSocketClient extends EventEmitter {
     constructor(url, config, getClient) {
         super();
-        this.closing = false;
-        this.closed = false;
+        /**
+         * One value rather than a pair of booleans plus a promise that could
+         * disagree with them. `closing` carries the in-flight close so a second
+         * caller joins it instead of returning while the first `disconnect()` is
+         * still running — which is how teardown reached `free()` on a busy client.
+         */
+        this.closeState = { phase: 'open' };
         this.listenerMutationDepth = 0;
         this.url = url instanceof URL ? url : new URL(url);
         this.config = config;
@@ -24,13 +29,13 @@ export class WebSocketClient extends EventEmitter {
         return this.getClient()?.isConnected() ?? false;
     }
     get isClosed() {
-        return this.closed;
+        return this.closeState.phase === 'closed';
     }
     get isClosing() {
-        return this.closing;
+        return this.closeState.phase === 'closing';
     }
     get isConnecting() {
-        return !this.isOpen && !this.closing && !this.closed;
+        return !this.isOpen && this.closeState.phase === 'open';
     }
     get hasRawNodeListeners() {
         return this.eventNames().some(eventName => isRawNodeEventName(eventName));
@@ -84,20 +89,44 @@ export class WebSocketClient extends EventEmitter {
         const client = this.getClient();
         if (!client || client.isConnected())
             return;
-        this.closed = false;
+        // A close in flight has already told the client to disconnect, which is
+        // exactly what makes `isConnected()` false above. Reopening here would
+        // clear the `closing` phase, and the next `close()` would start a second
+        // disconnect against the same client while the first is still running.
+        if (this.closeState.phase === 'closing')
+            return;
+        this.closeState = { phase: 'open' };
         void client.connect().catch(error => this.emit('error', error));
     }
+    /**
+     * Idempotent, and a second caller joins the first rather than returning
+     * while it is still going.
+     *
+     * The early return used to be bare: `void ws.close(); await sock.end()` saw
+     * the flag, returned immediately, and let teardown reach `free()` with the
+     * original `disconnect()` still in flight — the wasm heap corruption
+     * `bridge-free-safety.test.ts` documents. Awaiting a *second* `disconnect()`
+     * does not join the first one.
+     *
+     * The state is stored before `disconnect()` is called, and the work is
+     * deferred by a microtask to make that ordering hold: an inline async body
+     * runs eagerly to its first `await`, so `disconnect()` would be invoked
+     * while the state still said `open`, and anything it reaches synchronously
+     * that calls back into `close()` would issue a second one.
+     */
     async close() {
-        if (this.closing || this.closed)
-            return;
-        this.closing = true;
-        try {
-            await this.getClient()?.disconnect();
-        }
-        finally {
-            this.closing = false;
-            this.closed = true;
-        }
+        if (this.closeState.phase !== 'open')
+            return this.closeState.done;
+        const done = Promise.resolve().then(async () => {
+            try {
+                await this.getClient()?.disconnect();
+            }
+            finally {
+                this.closeState = { phase: 'closed', done };
+            }
+        });
+        this.closeState = { phase: 'closing', done };
+        return done;
     }
     send(str, cb) {
         const client = this.getClient();
@@ -110,9 +139,9 @@ export class WebSocketClient extends EventEmitter {
     get readyState() {
         if (this.isOpen)
             return 1;
-        if (this.closing)
+        if (this.closeState.phase === 'closing')
             return 2;
-        if (this.closed)
+        if (this.closeState.phase === 'closed')
             return 3;
         return 0;
     }

package/lib/Socket/bridge-client-owner.d.ts

@@ -0,0 +1,89 @@
+/**
+ * Owns the bridge client's lifetime.
+ *
+ * The socket's startup is async and its teardown can start at any point during
+ * it — a `sock.end()` right after `makeWASocket()`, an `await using` scope
+ * exiting, or a terminal disconnect the dispatcher reports while `init()` is
+ * still building the client. That window used to be managed by hand across six
+ * closure variables and a scattering of `if (ended) return` checks, which is
+ * where every teardown bug in this file came from: startup dereferencing a
+ * handle teardown had already nulled, a client built after teardown with
+ * nobody left to free it, an `end()` that resolved for its second caller while
+ * the first was still flushing, and a re-entrant close releasing the same wasm
+ * handle twice.
+ *
+ * All of those are one question — *what phase is this client in?* — so it is
+ * one discriminated union rather than a set of booleans that can disagree:
+ *
+ * ```
+ *   starting ──adopt()──► running ──close()──► closing ──► closed
+ *      │                     │                    ▲
+ *      └──────close()────────┴──discard()─────────┘
+ * ```
+ *
+ * Two rules make the whole thing safe, and both are properties of the union
+ * rather than of any individual method:
+ *
+ *  - **The transition is synchronous and happens first.** `close()` publishes
+ *    `closing` — carrying the promise callers await — before any teardown work
+ *    starts, so re-entering it finds an in-flight close instead of starting a
+ *    second one. That is why the work is deferred by a microtask rather than
+ *    started inline: an async body would otherwise run eagerly to its first
+ *    `await`, i.e. before the state was stored.
+ *  - **`closing` still carries the client.** The socket's transport close
+ *    reads it back through `peek()` (`ws.close()` is `getClient()?.disconnect()`),
+ *    so dropping the handle at the start of teardown silently turns that into
+ *    a no-op and moves the disconnect after the auth-store flush. `isClosing()`
+ *    — not `peek()` — is the "should I still be doing work" signal.
+ */
+import type { WasmWhatsAppClient } from '@oxidezap/whatsapp-rust-bridge';
+import type { ILogger } from '../Utils/logger.js';
+export interface BridgeClientOwnerOptions {
+    logger: ILogger;
+    /**
+     * The socket's own shutdown work. Receives the adopted client, if there is
+     * one, while it is still usable, and the error teardown was started with.
+     *
+     * Runs once. Throwing propagates to `close()`'s callers; the client is
+     * released either way.
+     */
+    teardown: (client: WasmWhatsAppClient | undefined, error: Error | undefined) => Promise<void>;
+    /**
+     * Hand the client back to the bridge. Separate from `teardown` because
+     * ordering matters and the two have different failure semantics: this one
+     * is best-effort and never throws out.
+     */
+    release: (client: WasmWhatsAppClient) => Promise<void>;
+}
+export interface BridgeClientOwner {
+    /** The client while `running` or `closing`; undefined before and after. */
+    peek: () => WasmWhatsAppClient | undefined;
+    /**
+     * Publish a freshly built client. Returns `false` when teardown has already
+     * started — the client is released here and the caller must stop, because
+     * nothing else will ever own it.
+     */
+    adopt: (client: WasmWhatsAppClient) => boolean;
+    /** True from the moment `close()` is called. Startup checks it between awaits. */
+    isClosing: () => boolean;
+    /** Runs teardown once; later callers await that same run. */
+    close: (error: Error | undefined) => Promise<void>;
+    /**
+     * Drop the client without tearing the socket down — for a startup that
+     * failed after adopting, where the client exists but its read loop never
+     * started. Joins an in-flight close rather than releasing a client that
+     * close already owns.
+     */
+    discard: () => Promise<void>;
+    /**
+     * Resolves once every release this owner started has finished, including
+     * the one a refused `adopt()` kicks off. Startup awaits it on the way out
+     * so its own promise does not settle with a release still in flight.
+     *
+     * A release can outlive the set it started in, so this drains rather than
+     * awaiting one snapshot.
+     */
+    settled: () => Promise<void>;
+}
+export declare const makeBridgeClientOwner: (opts: BridgeClientOwnerOptions) => BridgeClientOwner;
+//# sourceMappingURL=bridge-client-owner.d.ts.map

package/lib/Socket/bridge-client-owner.js

@@ -0,0 +1,135 @@
+/**
+ * Owns the bridge client's lifetime.
+ *
+ * The socket's startup is async and its teardown can start at any point during
+ * it — a `sock.end()` right after `makeWASocket()`, an `await using` scope
+ * exiting, or a terminal disconnect the dispatcher reports while `init()` is
+ * still building the client. That window used to be managed by hand across six
+ * closure variables and a scattering of `if (ended) return` checks, which is
+ * where every teardown bug in this file came from: startup dereferencing a
+ * handle teardown had already nulled, a client built after teardown with
+ * nobody left to free it, an `end()` that resolved for its second caller while
+ * the first was still flushing, and a re-entrant close releasing the same wasm
+ * handle twice.
+ *
+ * All of those are one question — *what phase is this client in?* — so it is
+ * one discriminated union rather than a set of booleans that can disagree:
+ *
+ * ```
+ *   starting ──adopt()──► running ──close()──► closing ──► closed
+ *      │                     │                    ▲
+ *      └──────close()────────┴──discard()─────────┘
+ * ```
+ *
+ * Two rules make the whole thing safe, and both are properties of the union
+ * rather than of any individual method:
+ *
+ *  - **The transition is synchronous and happens first.** `close()` publishes
+ *    `closing` — carrying the promise callers await — before any teardown work
+ *    starts, so re-entering it finds an in-flight close instead of starting a
+ *    second one. That is why the work is deferred by a microtask rather than
+ *    started inline: an async body would otherwise run eagerly to its first
+ *    `await`, i.e. before the state was stored.
+ *  - **`closing` still carries the client.** The socket's transport close
+ *    reads it back through `peek()` (`ws.close()` is `getClient()?.disconnect()`),
+ *    so dropping the handle at the start of teardown silently turns that into
+ *    a no-op and moves the disconnect after the auth-store flush. `isClosing()`
+ *    — not `peek()` — is the "should I still be doing work" signal.
+ */
+export const makeBridgeClientOwner = (opts) => {
+    const { logger, teardown, release } = opts;
+    let state = { phase: 'starting' };
+    /** Releases started outside `close()`, so `settled()` can join them. */
+    const pendingReleases = new Set();
+    const releaseQuietly = async (target) => {
+        try {
+            await release(target);
+        }
+        catch (err) {
+            logger.error({ err }, 'failed to release the bridge client');
+        }
+    };
+    /** `releaseQuietly`, but joinable through `settled()`. */
+    const trackRelease = (target) => {
+        const running = releaseQuietly(target).finally(() => pendingReleases.delete(running));
+        pendingReleases.add(running);
+        return running;
+    };
+    /** Drain releases started outside this close — see `runClose`. */
+    const drainReleases = async () => {
+        while (pendingReleases.size)
+            await Promise.all(pendingReleases);
+    };
+    const runClose = async (client, error, done) => {
+        try {
+            await teardown(client, error);
+        }
+        finally {
+            state = { phase: 'closed', done };
+            if (client)
+                await releaseQuietly(client);
+            // A `discard()` in flight when this close started put the client
+            // back in `starting`, so the capture above found none and teardown
+            // ran without it. Its release is still going: joining here keeps
+            // `close()` from settling while a client is being disconnected and
+            // freed, which is what the caller is told it can rely on.
+            await drainReleases();
+        }
+    };
+    return {
+        peek: () => (state.phase === 'running' || state.phase === 'closing' ? state.client : undefined),
+        adopt: candidate => {
+            if (state.phase !== 'starting') {
+                // Teardown has already been through here and found nothing, so
+                // this client would have no owner: nothing would free it and its
+                // read loop would reconnect forever against a disposed socket.
+                void trackRelease(candidate);
+                return false;
+            }
+            state = { phase: 'running', client: candidate };
+            return true;
+        },
+        isClosing: () => state.phase === 'closing' || state.phase === 'closed',
+        close: error => {
+            if (state.phase === 'closing' || state.phase === 'closed') {
+                logger.trace({ trace: error?.stack }, 'already closing; awaiting the in-flight teardown');
+                return state.done;
+            }
+            const client = state.phase === 'running' ? state.client : undefined;
+            // Deferred by a microtask so the `closing` state below is stored
+            // before any teardown work runs. Calling `runClose` inline would
+            // execute its body eagerly up to the first `await` — teardown starts
+            // by closing the transport — and anything reached synchronously that
+            // calls back into `close()` would find no in-flight close and start
+            // a second teardown, releasing the same wasm handle twice.
+            const done = Promise.resolve().then(() => runClose(client, error, done));
+            state = { phase: 'closing', client, done };
+            return done;
+        },
+        discard: async () => {
+            // `close()` owns the client from the moment it starts, and keeps it
+            // published for the whole of teardown — releasing it here as well
+            // would be two disconnect/free sequences on one handle. Join instead.
+            //
+            // Joining without adopting the failure: `close()` rejects when
+            // teardown rethrows the first auth-store flush error, and this is
+            // best-effort cleanup called from `init()`'s catch. Propagating it
+            // would make `initPromise` reject — which the socket documents as
+            // impossible, relies on for `getClient()`'s error message, and does
+            // not always await, so it could surface as an unhandled rejection.
+            if (state.phase === 'closing' || state.phase === 'closed') {
+                await state.done.catch(() => { });
+                return;
+            }
+            if (state.phase !== 'running')
+                return;
+            const { client } = state;
+            // Back to `starting`, not `closed`: a later `close()` must still run
+            // teardown for everything the socket owns beyond the client.
+            state = { phase: 'starting' };
+            await trackRelease(client);
+        },
+        settled: drainReleases
+    };
+};
+//# sourceMappingURL=bridge-client-owner.js.map

package/lib/Socket/events.d.ts

@@ -20,6 +20,37 @@ interface EventCallbacks {
     onDirtyState?: (event: Extract<CanonicalEvent, {
         type: 'dirtyState';
     }>) => void;
+    /**
+     * The engine has stopped reconnecting: this client is dead weight only
+     * `free()` can reclaim.
+     *
+     * Owns publishing the `close` too — `publish()` must be called, and the
+     * point of handing it over is that the socket can finish tearing down
+     * first. Upstream does the same, emitting its close only after `ws.close()`
+     * and the end handlers (`Socket/socket.ts`). A consumer answering `close`
+     * with a replacement socket on the same auth folder would otherwise race
+     * the old one's store flush and `free()`.
+     */
+    onTerminalClose?: (error: Error, publish: () => void) => void;
+    /**
+     * Hand back a cleanup for anything the dispatcher armed that outlives a
+     * single event — today the history-sync pause timer. The socket registers
+     * it as an end handler, so a plain `sock.end()` or an `await using` scope
+     * exiting cancels it too: only the terminal-close path goes through
+     * `emitClose`, and a timer surviving disposal fires
+     * `messaging-history.status: paused` from a socket that is already gone.
+     *
+     * Called once, during `makeEventHandlers`.
+     */
+    onCleanup?: (cleanup: () => void) => void;
+    /**
+     * Whether `sock.setAutoReconnect(true)` is in effect. A plain drop is only
+     * transient while the engine still intends to retry: with auto-reconnect
+     * off, the run loop dispatches `Disconnected` and then breaks for good
+     * (`client/lifecycle.rs` tests the flag *after* the dispatch), so the same
+     * event becomes terminal. Absent callback means the default, enabled.
+     */
+    isAutoReconnectEnabled?: () => boolean;
 }
 /**
  * Create typed single and batch handlers for the bridge. The bridge only uses