@yaebal/runner 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 neverlane
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,36 @@
+# @yaebal/runner
+
+concurrent update processing for yaebal bots. updates that share a chat id still run strictly in order; unrelated chats run in parallel up to `concurrency`.
+
+## install
+
+```sh
+pnpm add @yaebal/runner
+```
+
+## usage
+
+```ts
+import { run } from "@yaebal/runner";
+
+const handle = run(bot, {
+  concurrency: 50,   // max parallel updates (default 50)
+  limit: 100,        // getUpdates batch size (default 100)
+  timeout: 30,       // long-poll timeout in seconds (default 30)
+  onError: (err, update) => console.error(update?.update_id, err),
+});
+
+// graceful shutdown
+process.once("SIGINT", () => handle.stop());
+```
+
+use `createScheduler` directly if you need the bounded-concurrency queue for other purposes:
+
+```ts
+import { createScheduler } from "@yaebal/runner";
+
+const scheduler = createScheduler(10);
+scheduler.submit(chatId, async () => { /* ... */ });
+
+await scheduler.idle();
+```

package/lib/index.d.ts

@@ -0,0 +1,48 @@
+import type { Update } from "@yaebal/types";
+/**
+ * @yaebal/runner — drives a bot with CONCURRENT update processing instead of the
+ * built-in sequential long-poll. updates that share a key (the chat id, by
+ * default) still run strictly in order, so per-chat state (sessions) stays safe;
+ * unrelated chats run in parallel up to `concurrency`.
+ */
+export interface Scheduler {
+    /** queue a task. tasks with the same non-null `key` run in submit order, never overlapping. */
+    submit(key: PropertyKey | undefined, task: () => Promise<void>): void;
+    /** resolves once nothing is queued or running. */
+    idle(): Promise<void>;
+    /** resolves once fewer than `n` tasks are queued or running (backpressure gate). */
+    whenBelow(n: number): Promise<void>;
+    /** tasks currently queued or running. */
+    size(): number;
+}
+/** a bounded-concurrency scheduler with optional per-key sequentialization. */
+export declare function createScheduler(concurrency: number): Scheduler;
+/** extract the default sequentialization key (chat id, falling back to the actor's user id). */
+export declare function chatKey(update: Update): number | undefined;
+export interface RunnerBot {
+    api: {
+        getUpdates(params?: Record<string, unknown>): Promise<Update[]>;
+    };
+    handleUpdate(update: Update): Promise<void>;
+}
+export interface RunnerOptions {
+    /** max updates processed at once. defaults to 50. */
+    concurrency?: number;
+    /** map an update to a key whose updates must stay ordered. defaults to chat id. `undefined` = no ordering. */
+    sequentializeBy?: (update: Update) => PropertyKey | undefined;
+    /** getUpdates batch size. defaults to 100. */
+    limit?: number;
+    /** long-poll timeout (seconds). defaults to 30. */
+    timeout?: number;
+    /** restrict update types (telegram `allowed_updates`). */
+    allowedUpdates?: string[];
+    /** called on a handler or polling error. */
+    onError?: (error: unknown, update?: Update) => void;
+}
+export interface RunnerHandle {
+    /** stop polling and wait for in-flight updates to drain. */
+    stop(): Promise<void>;
+}
+/** start driving `bot` concurrently. returns a handle whose `stop()` drains in-flight work. */
+export declare function run(bot: RunnerBot, options?: RunnerOptions): RunnerHandle;
+//# sourceMappingURL=index.d.ts.map

package/lib/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,eAAe,CAAC;AAE5C;;;;;GAKG;AAEH,MAAM,WAAW,SAAS;IACzB,+FAA+F;IAC/F,MAAM,CAAC,GAAG,EAAE,WAAW,GAAG,SAAS,EAAE,IAAI,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IACtE,kDAAkD;IAClD,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACtB,oFAAoF;IACpF,SAAS,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACpC,yCAAyC;IACzC,IAAI,IAAI,MAAM,CAAC;CACf;AAED,+EAA+E;AAC/E,wBAAgB,eAAe,CAAC,WAAW,EAAE,MAAM,GAAG,SAAS,CAyF9D;AAED,gGAAgG;AAChG,wBAAgB,OAAO,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAoB1D;AAED,MAAM,WAAW,SAAS;IACzB,GAAG,EAAE;QAAE,UAAU,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAAA;KAAE,CAAC;IACzE,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC5C;AAED,MAAM,WAAW,aAAa;IAC7B,qDAAqD;IACrD,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,8GAA8G;IAC9G,eAAe,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,WAAW,GAAG,SAAS,CAAC;IAC9D,8CAA8C;IAC9C,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,mDAAmD;IACnD,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,0DAA0D;IAC1D,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAC1B,4CAA4C;IAC5C,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,MAAM,CAAC,EAAE,MAAM,KAAK,IAAI,CAAC;CACpD;AAED,MAAM,WAAW,YAAY;IAC5B,4DAA4D;IAC5D,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACtB;AAID,+FAA+F;AAC/F,wBAAgB,GAAG,CAAC,GAAG,EAAE,SAAS,EAAE,OAAO,GAAE,aAAkB,GAAG,YAAY,CAsD7E"}

package/lib/index.js

@@ -0,0 +1,152 @@
+/** a bounded-concurrency scheduler with optional per-key sequentialization. */
+export function createScheduler(concurrency) {
+    let active = 0;
+    let pending = 0;
+    const slotWaiters = [];
+    const idleWaiters = [];
+    const belowWaiters = [];
+    const tails = new Map();
+    const acquire = () => new Promise((resolve) => {
+        if (active < concurrency) {
+            active++;
+            resolve();
+        }
+        else {
+            slotWaiters.push(() => {
+                active++;
+                resolve();
+            });
+        }
+    });
+    const release = () => {
+        active--;
+        slotWaiters.shift()?.();
+    };
+    const settle = () => {
+        pending--;
+        if (pending === 0)
+            for (const f of idleWaiters.splice(0))
+                f();
+        for (let i = belowWaiters.length - 1; i >= 0; i--) {
+            const w = belowWaiters[i];
+            if (w && pending < w.n) {
+                belowWaiters.splice(i, 1);
+                w.resolve();
+            }
+        }
+    };
+    const runTask = async (task) => {
+        await acquire();
+        try {
+            await task();
+        }
+        catch {
+            // tasks are expected to handle their own errors (the runner wraps handleUpdate)
+        }
+        finally {
+            release();
+            settle();
+        }
+    };
+    return {
+        submit(key, task) {
+            pending++;
+            if (key == null) {
+                void runTask(task);
+                return;
+            }
+            const prev = tails.get(key) ?? Promise.resolve();
+            const next = prev.then(() => runTask(task), () => runTask(task));
+            tails.set(key, next);
+            void next.finally(() => {
+                if (tails.get(key) === next)
+                    tails.delete(key);
+            });
+        },
+        idle() {
+            return pending === 0
+                ? Promise.resolve()
+                : new Promise((resolve) => idleWaiters.push(resolve));
+        },
+        whenBelow(n) {
+            return pending < n
+                ? Promise.resolve()
+                : new Promise((resolve) => belowWaiters.push({ n, resolve }));
+        },
+        size() {
+            return pending;
+        },
+    };
+}
+/** extract the default sequentialization key (chat id, falling back to the actor's user id). */
+export function chatKey(update) {
+    const msg = update.message ??
+        update.edited_message ??
+        update.channel_post ??
+        update.edited_channel_post ??
+        update.callback_query?.message ??
+        update.my_chat_member ??
+        update.chat_member ??
+        update.chat_join_request;
+    const chatId = msg?.chat?.id;
+    if (chatId != null)
+        return chatId;
+    return (update.callback_query?.from?.id ??
+        update.inline_query?.from?.id ??
+        update.poll_answer?.user?.id ??
+        undefined);
+}
+const delay = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+/** start driving `bot` concurrently. returns a handle whose `stop()` drains in-flight work. */
+export function run(bot, options = {}) {
+    const concurrency = options.concurrency ?? 50;
+    const seqBy = options.sequentializeBy ?? chatKey;
+    const scheduler = createScheduler(concurrency);
+    let stopped = false;
+    let offset = 0;
+    const safe = async (update) => {
+        try {
+            await bot.handleUpdate(update);
+        }
+        catch (error) {
+            options.onError?.(error, update);
+        }
+    };
+    const loop = async () => {
+        while (!stopped) {
+            if (scheduler.size() >= concurrency)
+                await scheduler.whenBelow(concurrency);
+            if (stopped)
+                break;
+            let updates;
+            try {
+                updates = await bot.api.getUpdates({
+                    offset,
+                    limit: options.limit ?? 100,
+                    timeout: options.timeout ?? 30,
+                    ...(options.allowedUpdates ? { allowed_updates: options.allowedUpdates } : {}),
+                });
+            }
+            catch (error) {
+                if (stopped)
+                    break;
+                options.onError?.(error);
+                await delay(3000);
+                continue;
+            }
+            for (const update of updates) {
+                offset = update.update_id + 1;
+                scheduler.submit(seqBy(update), () => safe(update));
+            }
+        }
+    };
+    const loopDone = loop();
+    return {
+        async stop() {
+            stopped = true;
+            await loopDone;
+            await scheduler.idle();
+        },
+    };
+}
+//# sourceMappingURL=index.js.map

package/lib/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/lib/index.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=index.test.d.ts.map

package/lib/index.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.test.d.ts","sourceRoot":"","sources":["../src/index.test.ts"],"names":[],"mappings":""}

package/lib/index.test.js

@@ -0,0 +1,111 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { chatKey, createScheduler, run } from "./index.js";
+const tick = () => new Promise((r) => setTimeout(r, 0));
+function deferred() {
+    let resolve;
+    const promise = new Promise((r) => {
+        resolve = r;
+    });
+    return { promise, resolve };
+}
+test("scheduler: same key runs in order, never overlapping", async () => {
+    const s = createScheduler(5);
+    const log = [];
+    const a1 = deferred();
+    const a2 = deferred();
+    s.submit("A", async () => {
+        log.push("a1-start");
+        await a1.promise;
+        log.push("a1-end");
+    });
+    s.submit("A", async () => {
+        log.push("a2-start");
+        await a2.promise;
+        log.push("a2-end");
+    });
+    await tick();
+    assert.deepEqual(log, ["a1-start"]); // a2 waits for a1 (same key)
+    a1.resolve();
+    await tick();
+    assert.deepEqual(log, ["a1-start", "a1-end", "a2-start"]);
+    a2.resolve();
+    await s.idle();
+    assert.deepEqual(log, ["a1-start", "a1-end", "a2-start", "a2-end"]);
+});
+test("scheduler: different keys run concurrently up to the limit", async () => {
+    const s = createScheduler(2);
+    const started = [];
+    const gates = [deferred(), deferred(), deferred()];
+    for (let i = 0; i < 3; i++) {
+        s.submit(`k${i}`, async () => {
+            started.push(`k${i}`);
+            await gates[i]?.promise;
+        });
+    }
+    await tick();
+    assert.deepEqual(started, ["k0", "k1"]); // 3rd is blocked by the concurrency cap
+    gates[0]?.resolve();
+    await tick();
+    assert.deepEqual(started, ["k0", "k1", "k2"]); // freed slot lets k2 start
+    gates[1]?.resolve();
+    gates[2]?.resolve();
+    await s.idle();
+});
+test("scheduler: whenBelow gates backpressure", async () => {
+    const s = createScheduler(10);
+    const g = deferred();
+    for (let i = 0; i < 3; i++)
+        s.submit(undefined, async () => await g.promise);
+    assert.equal(s.size(), 3);
+    let below = false;
+    void s.whenBelow(2).then(() => {
+        below = true;
+    });
+    await tick();
+    assert.equal(below, false);
+    g.resolve();
+    await s.idle();
+    await tick();
+    assert.equal(below, true);
+});
+test("chatKey: pulls chat id from common update shapes", () => {
+    assert.equal(chatKey({ update_id: 1, message: { chat: { id: 7 } } }), 7);
+    assert.equal(chatKey({ update_id: 2, callback_query: { message: { chat: { id: 9 } } } }), 9);
+    assert.equal(chatKey({ update_id: 3, callback_query: { from: { id: 5 } } }), 5);
+    assert.equal(chatKey({ update_id: 4 }), undefined);
+});
+test("run: processes a batch, keeps per-chat order, advances offset, drains on stop", async () => {
+    const order = [];
+    const offsets = [];
+    let delivered = false;
+    const bot = {
+        api: {
+            async getUpdates(params) {
+                offsets.push(Number(params?.offset ?? 0));
+                if (!delivered) {
+                    delivered = true;
+                    return [
+                        { update_id: 1, message: { chat: { id: 7 } } },
+                        { update_id: 2, message: { chat: { id: 7 } } },
+                        { update_id: 3, message: { chat: { id: 8 } } },
+                    ];
+                }
+                await tick();
+                return [];
+            },
+            // biome-ignore lint/suspicious/noExplicitAny: test mock
+        },
+        async handleUpdate(u) {
+            order.push(u.update_id);
+        },
+    };
+    const handle = run(bot, { concurrency: 5, timeout: 0 });
+    await tick();
+    await tick();
+    await handle.stop();
+    assert.ok(order.includes(1) && order.includes(2) && order.includes(3));
+    assert.ok(order.indexOf(1) < order.indexOf(2), "same chat stays ordered");
+    assert.ok(offsets.includes(4), "offset advanced past the batch");
+});
+//# sourceMappingURL=index.test.js.map

package/lib/index.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.test.js","sourceRoot":"","sources":["../src/index.test.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@yaebal/runner",
+  "version": "0.0.1",
+  "description": "yaebal runner — concurrent update processing with per-chat sequentialization.",
+  "type": "module",
+  "main": "./lib/index.js",
+  "types": "./lib/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "import": "./lib/index.js"
+    }
+  },
+  "files": [
+    "lib",
+    "src"
+  ],
+  "dependencies": {
+    "@yaebal/types": "0.0.1"
+  },
+  "devDependencies": {
+    "@types/node": "latest"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "keywords": [
+    "telegram",
+    "telegram-bot",
+    "yaebal",
+    "runner",
+    "concurrency"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/neverlane/yaebal",
+    "directory": "packages/runner"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "node --test lib"
+  }
+}

package/src/index.test.ts

@@ -0,0 +1,148 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { chatKey, createScheduler, run } from "./index.js";
+
+const tick = () => new Promise<void>((r) => setTimeout(r, 0));
+
+function deferred() {
+	let resolve!: () => void;
+
+	const promise = new Promise<void>((r) => {
+		resolve = r;
+	});
+
+	return { promise, resolve };
+}
+
+test("scheduler: same key runs in order, never overlapping", async () => {
+	const s = createScheduler(5);
+	const log: string[] = [];
+	const a1 = deferred();
+	const a2 = deferred();
+
+	s.submit("A", async () => {
+		log.push("a1-start");
+		await a1.promise;
+
+		log.push("a1-end");
+	});
+
+	s.submit("A", async () => {
+		log.push("a2-start");
+		await a2.promise;
+
+		log.push("a2-end");
+	});
+
+	await tick();
+	assert.deepEqual(log, ["a1-start"]); // a2 waits for a1 (same key)
+
+	a1.resolve();
+	await tick();
+	assert.deepEqual(log, ["a1-start", "a1-end", "a2-start"]);
+
+	a2.resolve();
+	await s.idle();
+	assert.deepEqual(log, ["a1-start", "a1-end", "a2-start", "a2-end"]);
+});
+
+test("scheduler: different keys run concurrently up to the limit", async () => {
+	const s = createScheduler(2);
+	const started: string[] = [];
+	const gates = [deferred(), deferred(), deferred()];
+
+	for (let i = 0; i < 3; i++) {
+		s.submit(`k${i}`, async () => {
+			started.push(`k${i}`);
+			await gates[i]?.promise;
+		});
+	}
+
+	await tick();
+	assert.deepEqual(started, ["k0", "k1"]); // 3rd is blocked by the concurrency cap
+
+	gates[0]?.resolve();
+	await tick();
+	assert.deepEqual(started, ["k0", "k1", "k2"]); // freed slot lets k2 start
+
+	gates[1]?.resolve();
+	gates[2]?.resolve();
+	await s.idle();
+});
+
+test("scheduler: whenBelow gates backpressure", async () => {
+	const s = createScheduler(10);
+	const g = deferred();
+
+	for (let i = 0; i < 3; i++) s.submit(undefined, async () => await g.promise);
+	assert.equal(s.size(), 3);
+
+	let below = false;
+	void s.whenBelow(2).then(() => {
+		below = true;
+	});
+
+	await tick();
+	assert.equal(below, false);
+
+	g.resolve();
+
+	await s.idle();
+	await tick();
+
+	assert.equal(below, true);
+});
+
+test("chatKey: pulls chat id from common update shapes", () => {
+	assert.equal(chatKey({ update_id: 1, message: { chat: { id: 7 } } } as never), 7);
+
+	assert.equal(
+		chatKey({ update_id: 2, callback_query: { message: { chat: { id: 9 } } } } as never),
+		9,
+	);
+
+	assert.equal(chatKey({ update_id: 3, callback_query: { from: { id: 5 } } } as never), 5);
+	assert.equal(chatKey({ update_id: 4 } as never), undefined);
+});
+
+test("run: processes a batch, keeps per-chat order, advances offset, drains on stop", async () => {
+	const order: number[] = [];
+	const offsets: number[] = [];
+	let delivered = false;
+
+	const bot = {
+		api: {
+			async getUpdates(params?: Record<string, unknown>) {
+				offsets.push(Number(params?.offset ?? 0));
+
+				if (!delivered) {
+					delivered = true;
+
+					return [
+						{ update_id: 1, message: { chat: { id: 7 } } },
+						{ update_id: 2, message: { chat: { id: 7 } } },
+						{ update_id: 3, message: { chat: { id: 8 } } },
+					] as never;
+				}
+
+				await tick();
+				return [] as never;
+			},
+			// biome-ignore lint/suspicious/noExplicitAny: test mock
+		} as any,
+		async handleUpdate(u: { update_id: number }) {
+			order.push(u.update_id);
+		},
+	};
+
+	const handle = run(bot, { concurrency: 5, timeout: 0 });
+
+	await tick();
+	await tick();
+	
+	await handle.stop();
+
+	assert.ok(order.includes(1) && order.includes(2) && order.includes(3));
+	assert.ok(order.indexOf(1) < order.indexOf(2), "same chat stays ordered");
+	assert.ok(offsets.includes(4), "offset advanced past the batch");
+});

package/src/index.ts

@@ -0,0 +1,218 @@
+import type { Update } from "@yaebal/types";
+
+/**
+ * @yaebal/runner — drives a bot with CONCURRENT update processing instead of the
+ * built-in sequential long-poll. updates that share a key (the chat id, by
+ * default) still run strictly in order, so per-chat state (sessions) stays safe;
+ * unrelated chats run in parallel up to `concurrency`.
+ */
+
+export interface Scheduler {
+	/** queue a task. tasks with the same non-null `key` run in submit order, never overlapping. */
+	submit(key: PropertyKey | undefined, task: () => Promise<void>): void;
+	/** resolves once nothing is queued or running. */
+	idle(): Promise<void>;
+	/** resolves once fewer than `n` tasks are queued or running (backpressure gate). */
+	whenBelow(n: number): Promise<void>;
+	/** tasks currently queued or running. */
+	size(): number;
+}
+
+/** a bounded-concurrency scheduler with optional per-key sequentialization. */
+export function createScheduler(concurrency: number): Scheduler {
+	let active = 0;
+	let pending = 0;
+
+	const slotWaiters: (() => void)[] = [];
+	const idleWaiters: (() => void)[] = [];
+	const belowWaiters: { n: number; resolve: () => void }[] = [];
+	const tails = new Map<PropertyKey, Promise<void>>();
+
+	const acquire = () =>
+		new Promise<void>((resolve) => {
+			if (active < concurrency) {
+				active++;
+				resolve();
+			} else {
+				slotWaiters.push(() => {
+					active++;
+					resolve();
+				});
+			}
+		});
+
+	const release = () => {
+		active--;
+		slotWaiters.shift()?.();
+	};
+
+	const settle = () => {
+		pending--;
+
+		if (pending === 0) for (const f of idleWaiters.splice(0)) f();
+
+		for (let i = belowWaiters.length - 1; i >= 0; i--) {
+			const w = belowWaiters[i];
+
+			if (w && pending < w.n) {
+				belowWaiters.splice(i, 1);
+				w.resolve();
+			}
+		}
+	};
+
+	const runTask = async (task: () => Promise<void>) => {
+		await acquire();
+
+		try {
+			await task();
+		} catch {
+			// tasks are expected to handle their own errors (the runner wraps handleUpdate)
+		} finally {
+			release();
+			settle();
+		}
+	};
+
+	return {
+		submit(key, task) {
+			pending++;
+
+			if (key == null) {
+				void runTask(task);
+				return;
+			}
+
+			const prev = tails.get(key) ?? Promise.resolve();
+			const next = prev.then(
+				() => runTask(task),
+				() => runTask(task),
+			);
+
+			tails.set(key, next);
+			void next.finally(() => {
+				if (tails.get(key) === next) tails.delete(key);
+			});
+		},
+		idle() {
+			return pending === 0
+				? Promise.resolve()
+				: new Promise((resolve) => idleWaiters.push(resolve));
+		},
+		whenBelow(n) {
+			return pending < n
+				? Promise.resolve()
+				: new Promise((resolve) => belowWaiters.push({ n, resolve }));
+		},
+		size() {
+			return pending;
+		},
+	};
+}
+
+/** extract the default sequentialization key (chat id, falling back to the actor's user id). */
+export function chatKey(update: Update): number | undefined {
+	const msg =
+		update.message ??
+		update.edited_message ??
+		update.channel_post ??
+		update.edited_channel_post ??
+		update.callback_query?.message ??
+		update.my_chat_member ??
+		update.chat_member ??
+		update.chat_join_request;
+
+	const chatId = msg?.chat?.id;
+	if (chatId != null) return chatId;
+
+	return (
+		update.callback_query?.from?.id ??
+		update.inline_query?.from?.id ??
+		update.poll_answer?.user?.id ??
+		undefined
+	);
+}
+
+export interface RunnerBot {
+	api: { getUpdates(params?: Record<string, unknown>): Promise<Update[]> };
+	handleUpdate(update: Update): Promise<void>;
+}
+
+export interface RunnerOptions {
+	/** max updates processed at once. defaults to 50. */
+	concurrency?: number;
+	/** map an update to a key whose updates must stay ordered. defaults to chat id. `undefined` = no ordering. */
+	sequentializeBy?: (update: Update) => PropertyKey | undefined;
+	/** getUpdates batch size. defaults to 100. */
+	limit?: number;
+	/** long-poll timeout (seconds). defaults to 30. */
+	timeout?: number;
+	/** restrict update types (telegram `allowed_updates`). */
+	allowedUpdates?: string[];
+	/** called on a handler or polling error. */
+	onError?: (error: unknown, update?: Update) => void;
+}
+
+export interface RunnerHandle {
+	/** stop polling and wait for in-flight updates to drain. */
+	stop(): Promise<void>;
+}
+
+const delay = (ms: number) => new Promise<void>((resolve) => setTimeout(resolve, ms));
+
+/** start driving `bot` concurrently. returns a handle whose `stop()` drains in-flight work. */
+export function run(bot: RunnerBot, options: RunnerOptions = {}): RunnerHandle {
+	const concurrency = options.concurrency ?? 50;
+	const seqBy = options.sequentializeBy ?? chatKey;
+	const scheduler = createScheduler(concurrency);
+
+	let stopped = false;
+	let offset = 0;
+
+	const safe = async (update: Update) => {
+		try {
+			await bot.handleUpdate(update);
+		} catch (error) {
+			options.onError?.(error, update);
+		}
+	};
+
+	const loop = async () => {
+		while (!stopped) {
+			if (scheduler.size() >= concurrency) await scheduler.whenBelow(concurrency);
+			if (stopped) break;
+	
+			let updates: Update[];
+			try {
+				updates = await bot.api.getUpdates({
+					offset,
+					limit: options.limit ?? 100,
+					timeout: options.timeout ?? 30,
+					...(options.allowedUpdates ? { allowed_updates: options.allowedUpdates } : {}),
+				});
+			} catch (error) {
+				if (stopped) break;
+	
+				options.onError?.(error);
+				await delay(3000);
+	
+				continue;
+			}
+	
+			for (const update of updates) {
+				offset = update.update_id + 1;
+				scheduler.submit(seqBy(update), () => safe(update));
+			}
+		}
+	};
+
+	const loopDone = loop();
+
+	return {
+		async stop() {
+			stopped = true;
+			await loopDone;
+			await scheduler.idle();
+		},
+	};
+}