stitchkit 0.100.1 → 0.100.3

package/dist/telegram/screens/test-chat.d.ts

@@ -0,0 +1,66 @@
+/**
+ * A chat with the application's own bot, and no Telegram.
+ *
+ * `createScreenTestChat(bot)` takes the `Bot` the application composes — its
+ * middleware, commands and error boundary, in their real order — and answers
+ * its Bot API calls from memory through `bot.api.config.use`. Updates enter
+ * through `bot.handleUpdate`, so what a test proves is what the bot does:
+ * that `/support` is not swallowed by a screen waiting for text, that a press
+ * edits the message it came from.
+ *
+ * The Telegram it talks to is `test-chat-telegram.ts`, which keeps the rules
+ * screens depend on. Nothing here imports grammY at run time; the bot brings it.
+ */
+import type { Bot, Context } from 'grammy';
+import type { InlineKeyboardMarkup } from 'grammy/types';
+import { type TestMessageKind } from './test-chat-telegram.js';
+/** A message as the user sees it. */
+export interface TestChatMessage {
+    readonly id: number;
+    readonly from: 'bot' | 'user';
+    readonly kind: TestMessageKind;
+    /** The text, or the caption, as sent — Telegram HTML for the bot's messages. */
+    readonly text: string;
+    readonly media: string | undefined;
+    readonly rich: unknown;
+    /** Button labels, row by row. */
+    readonly buttons: readonly (readonly string[])[];
+    readonly markup: InlineKeyboardMarkup | undefined;
+}
+export interface TestChatCall {
+    readonly method: string;
+    readonly payload: Readonly<Record<string, unknown>>;
+}
+export interface TestChatOptions {
+    readonly chatId?: number;
+    readonly chatType?: 'private' | 'group' | 'supergroup';
+    readonly userId?: number;
+}
+export interface ScreenTestChat<C extends Context = Context> {
+    /** What the chat shows, top to bottom. */
+    readonly messages: readonly TestChatMessage[];
+    /** Every Bot API call the bot made, in order. */
+    readonly calls: readonly TestChatCall[];
+    /** Press answers — the toasts — in order; `''` for a silent answer. */
+    readonly answers: readonly string[];
+    /** The user sends text; a leading `/word` is a command. */
+    send(text: string): Promise<void>;
+    /** The user sends a photo, with an optional caption. */
+    sendPhoto(fileId: string, caption?: string): Promise<void>;
+    /** The user presses the lowest button with this label. */
+    press(label: string): Promise<void>;
+    /** A press carrying arbitrary `callback_data` on a message — what a forged press looks like. */
+    pressData(messageId: number, data: string): Promise<void>;
+    /** Refuse the next call of `method` the way Telegram would. */
+    failNext(method: string, description: string, errorCode?: number): void;
+    /** The user deletes a message. */
+    deleteByUser(messageId: number): void;
+    /**
+     * The process restarted: the same chat, as Telegram keeps it, now answered by
+     * a new bot — built over the same storage, the way the application builds it.
+     */
+    restart(bot: Bot<C>): void;
+    clearCalls(): void;
+}
+export declare function createScreenTestChat<C extends Context>(first: Bot<C>, options?: TestChatOptions): ScreenTestChat<C>;
+//# sourceMappingURL=test-chat.d.ts.map

package/dist/telegram/screens/test-chat.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"test-chat.d.ts","sourceRoot":"","sources":["../../../src/telegram/screens/test-chat.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,KAAK,EAAE,GAAG,EAAY,OAAO,EAAE,MAAM,QAAQ,CAAC;AACrD,OAAO,KAAK,EAAE,oBAAoB,EAAkC,MAAM,cAAc,CAAC;AAEzF,OAAO,EAIL,KAAK,eAAe,EACrB,MAAM,sBAAsB,CAAC;AAE9B,qCAAqC;AACrC,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,IAAI,EAAE,KAAK,GAAG,MAAM,CAAC;IAC9B,QAAQ,CAAC,IAAI,EAAE,eAAe,CAAC;IAC/B,gFAAgF;IAChF,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,CAAC;IACnC,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IACvB,iCAAiC;IACjC,QAAQ,CAAC,OAAO,EAAE,SAAS,CAAC,SAAS,MAAM,EAAE,CAAC,EAAE,CAAC;IACjD,QAAQ,CAAC,MAAM,EAAE,oBAAoB,GAAG,SAAS,CAAC;CACnD;AAED,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;CACrD;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,QAAQ,CAAC,EAAE,SAAS,GAAG,OAAO,GAAG,YAAY,CAAC;IACvD,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,cAAc,CAAC,CAAC,SAAS,OAAO,GAAG,OAAO;IACzD,0CAA0C;IAC1C,QAAQ,CAAC,QAAQ,EAAE,SAAS,eAAe,EAAE,CAAC;IAC9C,iDAAiD;IACjD,QAAQ,CAAC,KAAK,EAAE,SAAS,YAAY,EAAE,CAAC;IACxC,uEAAuE;IACvE,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC,2DAA2D;IAC3D,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAClC,wDAAwD;IACxD,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC3D,0DAA0D;IAC1D,KAAK,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACpC,gGAAgG;IAChG,SAAS,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1D,+DAA+D;IAC/D,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACxE,kCAAkC;IAClC,YAAY,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACtC;;;OAGG;IACH,OAAO,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC;IAC3B,UAAU,IAAI,IAAI,CAAC;CACpB;AAED,wBAAgB,oBAAoB,CAAC,CAAC,SAAS,OAAO,EACpD,KAAK,EAAE,GAAG,CAAC,CAAC,CAAC,EACb,OAAO,GAAE,eAAoB,GAC5B,cAAc,CAAC,CAAC,CAAC,CAgLnB"}

package/dist/telegram/screens/view.d.ts

@@ -0,0 +1,89 @@
+/**
+ * What a screen shows: messages as plain objects.
+ *
+ * A view is data, so it can be compared. `{ text }` is a text message,
+ * `{ rich }` a Bot API rich message (Markdown, HTML or blocks, without file
+ * uploads) and `{ photo }` (or `video`, `animation`, `document`, `audio`) a
+ * media message with an optional caption; exactly one of those keys is
+ * present, and the type says so. A keyboard is rows of buttons where a row or a button may be `false`,
+ * `null` or `undefined` — a conditional row is written in the literal, not
+ * around it. Buttons are either screen buttons (`link`, `back`, an action) or
+ * any Telegram inline button that carries no `callback_data`, as Telegram
+ * spells it.
+ */
+import type { InlineKeyboardButton, InputRichMessageWithoutUpload } from 'grammy/types';
+import type { ActionValue } from './callback-codec.js';
+import type { TelegramText } from './html.js';
+import type { AnyTelegramScreen, ScreenLinkArgs } from './screen-types.js';
+export type ScreenMediaKind = 'photo' | 'video' | 'animation' | 'document' | 'audio';
+export declare const SCREEN_MEDIA_KINDS: readonly ScreenMediaKind[];
+/** A button label: its text, or its text with Telegram's style and custom-emoji icon. */
+export type ButtonLabel = string | Omit<InlineKeyboardButton.CallbackButton, 'callback_data'>;
+type ButtonTarget = {
+    readonly kind: 'link';
+    readonly screen: AnyTelegramScreen;
+    readonly params: Readonly<Record<string, ActionValue>>;
+} | {
+    readonly kind: 'back';
+} | {
+    readonly kind: 'action';
+    readonly screen: AnyTelegramScreen;
+    readonly params: Readonly<Record<string, ActionValue>>;
+    readonly action: string;
+    readonly input: Readonly<Record<string, ActionValue | undefined>> | undefined;
+};
+/** A button the screens runtime answers: it becomes `callback_data` when rendered. */
+export declare class ScreenButton {
+    readonly label: ButtonLabel;
+    readonly target: ButtonTarget;
+    constructor(label: ButtonLabel, target: ButtonTarget);
+}
+/** Any inline button Telegram answers itself — a URL, a Mini App, copy text, … */
+export type PlainKeyboardButton = Exclude<InlineKeyboardButton, InlineKeyboardButton.CallbackButton>;
+export type KeyboardButton = ScreenButton | PlainKeyboardButton;
+type Absent = false | null | undefined;
+export type KeyboardRow = readonly (KeyboardButton | Absent)[];
+export type Keyboard = readonly (KeyboardRow | Absent)[];
+interface ViewMessageCommon {
+    /**
+     * The message's identity across renders: two renders put the same key in the
+     * same Telegram message when they can. The default is `'main'` for the last
+     * message and `'s0'`, `'s1'`, … for those above it, so the message that
+     * carries a screen's buttons is the one the next screen edits.
+     */
+    readonly key?: string;
+    readonly keyboard?: Keyboard;
+}
+type ContentKey = 'text' | 'rich' | ScreenMediaKind;
+type Without<TKeys extends string> = {
+    readonly [K in TKeys]?: never;
+};
+export interface TextViewMessage extends ViewMessageCommon, Without<Exclude<ContentKey, 'text'> | 'caption'> {
+    readonly text: TelegramText;
+    /** `false` hides the preview of the first link. Default: Telegram's. */
+    readonly linkPreview?: boolean;
+}
+export interface RichViewMessage extends ViewMessageCommon, Without<Exclude<ContentKey, 'rich'> | 'caption' | 'linkPreview'> {
+    /** A rich message as the Bot API takes it; files by `file_id` or URL only. */
+    readonly rich: InputRichMessageWithoutUpload;
+}
+type MediaViewMessageOf<TKind extends ScreenMediaKind> = ViewMessageCommon & Without<Exclude<ContentKey, TKind> | 'linkPreview'> & {
+    /** A Telegram `file_id` or an HTTP URL Telegram can fetch. */
+    readonly [K in TKind]: string;
+} & {
+    readonly caption?: TelegramText;
+};
+export type PhotoViewMessage = MediaViewMessageOf<'photo'>;
+export type VideoViewMessage = MediaViewMessageOf<'video'>;
+export type AnimationViewMessage = MediaViewMessageOf<'animation'>;
+export type DocumentViewMessage = MediaViewMessageOf<'document'>;
+export type AudioViewMessage = MediaViewMessageOf<'audio'>;
+export type ViewMessage = TextViewMessage | RichViewMessage | PhotoViewMessage | VideoViewMessage | AnimationViewMessage | DocumentViewMessage | AudioViewMessage;
+/** What `view` returns: one message, or several shown top to bottom. */
+export type ScreenViewResult = ViewMessage | readonly ViewMessage[];
+/** A link to another screen; its params are required exactly when its path has any. */
+export declare function link<TScreen extends AnyTelegramScreen>(label: ButtonLabel, screen: TScreen, ...params: ScreenLinkArgs<TScreen>): ScreenButton;
+/** A link to the parent screen — the nearest declared screen above this path. */
+export declare function back(label: ButtonLabel): ScreenButton;
+export {};
+//# sourceMappingURL=view.d.ts.map

package/dist/telegram/screens/view.d.ts.map

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

package/dist/telegram/send-failure.d.ts

@@ -70,4 +70,23 @@ export interface TelegramSendFailure {
  * which asserts nothing about the recipient and permits no retry.
  */
 export declare function classifyTelegramSendFailure(error: unknown): TelegramSendFailure;
+/**
+ * What a refused edit, deletion or press answer means for the chat — the
+ * questions a screen asks after the message exists, which a send never does.
+ *
+ * - `not-modified`: the edit asked for what is already there. Success.
+ * - `message-gone`: the message is not there — the user deleted it, or the id
+ *   is not a message at all. A deletion of it has nothing left to do.
+ * - `message-locked`: the message is there and cannot be changed that way — too
+ *   old to delete, not the bot's to edit, no text or caption to edit. An edit
+ *   has to send it anew; a deletion leaves it in the chat.
+ * - `query-expired`: the press waited too long to be answered; nothing to do.
+ * - `other`: everything else, including a malformed payload — the caller's to
+ *   raise.
+ *
+ * Internal to the screens: it reads Telegram's prose the same way
+ * {@link classifyTelegramSendFailure} does and is not a public vocabulary.
+ */
+export type TelegramEditRefusal = 'not-modified' | 'message-gone' | 'message-locked' | 'query-expired' | 'other';
+export declare function classifyTelegramEditRefusal(error: unknown): TelegramEditRefusal;
 //# sourceMappingURL=send-failure.d.ts.map

package/dist/telegram/send-failure.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"send-failure.d.ts","sourceRoot":"","sources":["../../src/telegram/send-failure.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAIH;;;;;;;;;GASG;AACH,MAAM,MAAM,yBAAyB,GACjC,iBAAiB,GACjB,kBAAkB,GAClB,gBAAgB,GAChB,aAAa,GACb,cAAc,GACd,iBAAiB,GACjB,cAAc,GACd,SAAS,CAAC;AAEd,MAAM,WAAW,mBAAmB;IAClC,MAAM,EAAE,yBAAyB,CAAC;IAClC,6DAA6D;IAC7D,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;;;OAMG;IACH,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,wDAAwD;IACxD,SAAS,EAAE,OAAO,CAAC;IACnB;;;;;;;;OAQG;IACH,oBAAoB,EAAE,OAAO,CAAC;IAC9B;;;;OAIG;IACH,QAAQ,EAAE,YAAY,GAAG,QAAQ,GAAG,aAAa,GAAG,MAAM,CAAC;CAC5D;AAuED;;;;;GAKG;AACH,wBAAgB,2BAA2B,CAAC,KAAK,EAAE,OAAO,GAAG,mBAAmB,CA0D/E"}
+{"version":3,"file":"send-failure.d.ts","sourceRoot":"","sources":["../../src/telegram/send-failure.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAIH;;;;;;;;;GASG;AACH,MAAM,MAAM,yBAAyB,GACjC,iBAAiB,GACjB,kBAAkB,GAClB,gBAAgB,GAChB,aAAa,GACb,cAAc,GACd,iBAAiB,GACjB,cAAc,GACd,SAAS,CAAC;AAEd,MAAM,WAAW,mBAAmB;IAClC,MAAM,EAAE,yBAAyB,CAAC;IAClC,6DAA6D;IAC7D,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;;;OAMG;IACH,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,wDAAwD;IACxD,SAAS,EAAE,OAAO,CAAC;IACnB;;;;;;;;OAQG;IACH,oBAAoB,EAAE,OAAO,CAAC;IAC9B;;;;OAIG;IACH,QAAQ,EAAE,YAAY,GAAG,QAAQ,GAAG,aAAa,GAAG,MAAM,CAAC;CAC5D;AAuED;;;;;GAKG;AACH,wBAAgB,2BAA2B,CAAC,KAAK,EAAE,OAAO,GAAG,mBAAmB,CA0D/E;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,MAAM,mBAAmB,GAC3B,cAAc,GACd,cAAc,GACd,gBAAgB,GAChB,eAAe,GACf,OAAO,CAAC;AAeZ,wBAAgB,2BAA2B,CAAC,KAAK,EAAE,OAAO,GAAG,mBAAmB,CAM/E"}

package/dist/telegram/update-intake.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Webhook updates received durably: recorded before Telegram is answered,
+ * handled after, and never lost to a restart or a slow handler.
+ *
+ * Answering Telegram only after an update is handled breaks twice. A long
+ * handler — a file of gigabytes arriving from a local Bot API server — holds
+ * the connection past Telegram's patience, it gives up and sends the update
+ * again while the first attempt still runs; and a process that dies after
+ * handling but before answering loses nothing Telegram knows about, while one
+ * that dies before handling loses the update for good once it has answered.
+ * So the body is written first and Telegram answered at once; handling runs
+ * here, outside the request.
+ *
+ * Updates of one chat run one after another, in `update_id` order; different
+ * chats run side by side up to `maxConcurrent`. An attempt holds a lease that
+ * is renewed while its handler lives; a sweep takes over what was left —
+ * `pending` whose process never got to it, `failed` whose retry is due,
+ * `processing` whose lease nobody renewed. Delivery is at least once: a
+ * handler that finished but could not be recorded as finished runs again.
+ */
+import type { TelegramUpdateStore } from './update-store.js';
+import type { TelegramUpdateAcceptance } from './webhook.js';
+/** An update as Telegram sends it; name grammY's `Update` to get its full type. */
+export interface TelegramUpdateEnvelope {
+    readonly update_id: number;
+}
+export interface TelegramUpdateFailure {
+    readonly updateId: number;
+    readonly attempt: number;
+    readonly error: unknown;
+    /** `false` when the update was abandoned — no attempt follows. */
+    readonly retrying: boolean;
+}
+export type TelegramUpdateStoreStep = 'claim' | 'renew' | 'settle' | 'sweep';
+export interface TelegramUpdateIntakeConfig<TUpdate extends TelegramUpdateEnvelope> {
+    readonly store: TelegramUpdateStore;
+    /** Handle one update — with grammY, `(update) => bot.handleUpdate(update)`. */
+    readonly handle: (update: TUpdate) => unknown;
+    /**
+     * After a failed attempt: milliseconds until the next, or `false` to
+     * abandon the update. Default: abandon what Telegram said repeating cannot
+     * fix (a refused message, a blocked user), wait Telegram's `retry_after`
+     * when it gave one, otherwise back off 5 s, 20 s, 80 s … up to 15 minutes.
+     */
+    readonly retry?: (error: unknown, attempt: number) => number | false;
+    /** Default 5. */
+    readonly maxAttempts?: number;
+    /** How long an attempt holds its update without renewing. Default 120 000; renewed every quarter. */
+    readonly leaseMs?: number;
+    /** How long a `pending` update waits for this process before a sweep takes it. Default 60 000. */
+    readonly pendingGraceMs?: number;
+    /** Default 30 000. */
+    readonly sweepEveryMs?: number;
+    /** How long finished updates are remembered to refuse Telegram's repeats. Default 24 h. */
+    readonly retainMs?: number;
+    /** Chats handled at once. Default 32. */
+    readonly maxConcurrent?: number;
+    /** Every failed attempt. */
+    readonly onFailure?: (failure: TelegramUpdateFailure) => void;
+    /** The store refused a step; the update is retried when its lease lapses. */
+    readonly onStoreError?: (error: unknown, step: TelegramUpdateStoreStep) => void;
+    /** Default `Date.now`. */
+    readonly now?: () => number;
+}
+export interface TelegramUpdateIntake {
+    /** Record one webhook body; handling starts after, once the intake is started. */
+    accept(body: string): Promise<TelegramUpdateAcceptance>;
+    /** Start handling, beginning with everything recorded before. */
+    start(): Promise<void>;
+    /** Take over what is due now; how many updates were scheduled. */
+    sweep(): Promise<number>;
+    /** Resolves once nothing is scheduled. */
+    idle(): Promise<void>;
+    /** Stop scheduling and wait for the handlers in flight. */
+    close(): Promise<void>;
+}
+export declare function createTelegramUpdateIntake<TUpdate extends TelegramUpdateEnvelope>(config: TelegramUpdateIntakeConfig<TUpdate>): TelegramUpdateIntake;
+//# sourceMappingURL=update-intake.d.ts.map

package/dist/telegram/update-intake.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"update-intake.d.ts","sourceRoot":"","sources":["../../src/telegram/update-intake.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAIH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AAC1D,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,WAAW,CAAC;AAE1D,mFAAmF;AACnF,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAED,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,kEAAkE;IAClE,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;CAC5B;AAED,MAAM,MAAM,uBAAuB,GAAG,OAAO,GAAG,OAAO,GAAG,QAAQ,GAAG,OAAO,CAAC;AAE7E,MAAM,WAAW,0BAA0B,CAAC,OAAO,SAAS,sBAAsB;IAChF,QAAQ,CAAC,KAAK,EAAE,mBAAmB,CAAC;IACpC,+EAA+E;IAC/E,QAAQ,CAAC,MAAM,EAAE,CAAC,MAAM,EAAE,OAAO,KAAK,OAAO,CAAC;IAC9C;;;;;OAKG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,KAAK,MAAM,GAAG,KAAK,CAAC;IACrE,iBAAiB;IACjB,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,qGAAqG;IACrG,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,kGAAkG;IAClG,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;IACjC,sBAAsB;IACtB,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B,2FAA2F;IAC3F,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,yCAAyC;IACzC,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC,4BAA4B;IAC5B,QAAQ,CAAC,SAAS,CAAC,EAAE,CAAC,OAAO,EAAE,qBAAqB,KAAK,IAAI,CAAC;IAC9D,6EAA6E;IAC7E,QAAQ,CAAC,YAAY,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,uBAAuB,KAAK,IAAI,CAAC;IAChF,0BAA0B;IAC1B,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CAC7B;AAED,MAAM,WAAW,oBAAoB;IACnC,kFAAkF;IAClF,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,wBAAwB,CAAC,CAAC;IACxD,iEAAiE;IACjE,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACvB,kEAAkE;IAClE,KAAK,IAAI,OAAO,CAAC,MAAM,CAAC,CAAC;IACzB,0CAA0C;IAC1C,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACtB,2DAA2D;IAC3D,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAsDD,wBAAgB,0BAA0B,CAAC,OAAO,SAAS,sBAAsB,EAC/E,MAAM,EAAE,0BAA0B,CAAC,OAAO,CAAC,GAC1C,oBAAoB,CAgJtB"}

package/dist/telegram/update-store-sqlite.d.ts

@@ -0,0 +1,26 @@
+/**
+ * The update store in SQLite, through the database handle the application
+ * already opened — `bun:sqlite`'s `Database` or `node:sqlite`'s `DatabaseSync`
+ * as it is. The module imports neither, so it runs wherever its caller does.
+ *
+ * Each rule of `TelegramUpdateStore` is one conditional statement, so a claim
+ * is atomic across processes sharing the file.
+ */
+import type { TelegramUpdateStore } from './update-store.js';
+/** What this store needs of a SQLite handle; both runtimes' handles have it. */
+export interface TelegramSqliteDatabase {
+    exec(sql: string): unknown;
+    prepare(sql: string): {
+        run(...parameters: (string | number | null)[]): {
+            readonly changes: number | bigint;
+        };
+        all(...parameters: (string | number | null)[]): unknown[];
+    };
+}
+export interface SqliteTelegramUpdateStoreConfig {
+    readonly database: TelegramSqliteDatabase;
+    /** Default `telegram_updates`. Created when missing. */
+    readonly table?: string;
+}
+export declare function sqliteTelegramUpdateStore(config: SqliteTelegramUpdateStoreConfig): TelegramUpdateStore;
+//# sourceMappingURL=update-store-sqlite.d.ts.map

package/dist/telegram/update-store-sqlite.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"update-store-sqlite.d.ts","sourceRoot":"","sources":["../../src/telegram/update-store-sqlite.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAGV,mBAAmB,EACpB,MAAM,gBAAgB,CAAC;AAExB,gFAAgF;AAChF,MAAM,WAAW,sBAAsB;IACrC,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;IAC3B,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG;QACpB,GAAG,CAAC,GAAG,UAAU,EAAE,CAAC,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC,EAAE,GAAG;YAAE,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAAA;SAAE,CAAC;QACtF,GAAG,CAAC,GAAG,UAAU,EAAE,CAAC,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC,EAAE,GAAG,OAAO,EAAE,CAAC;KAC3D,CAAC;CACH;AAED,MAAM,WAAW,+BAA+B;IAC9C,QAAQ,CAAC,QAAQ,EAAE,sBAAsB,CAAC;IAC1C,wDAAwD;IACxD,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB;AAiBD,wBAAgB,yBAAyB,CACvC,MAAM,EAAE,+BAA+B,GACtC,mBAAmB,CAkFrB"}

package/dist/telegram/update-store.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Where received updates wait, and the rules a store keeps for them.
+ *
+ * The intake decides; the store only has to make each decision atomic, so two
+ * processes sharing one store — an old release still draining beside a new one
+ * — never run one update at once. Every rule is a condition on one record:
+ *
+ * - **claimable** at `now`: `pending`; `failed` whose `dueAt` has come;
+ *   `processing` whose lease (`dueAt`) has lapsed — its process died;
+ * - `claim` takes a claimable record whose `attempts` are under the limit —
+ *   `processing`, `attempts + 1`, lease until `leaseUntil` — and settles one
+ *   whose attempts are spent as `abandoned`;
+ * - `renew` and `settle` act only while the record is still `processing` under
+ *   the same attempt, so a process that lost its lease cannot overwrite the
+ *   one that took it over.
+ */
+export type TelegramUpdateState = 'pending' | 'processing' | 'failed' | 'completed' | 'abandoned';
+export type TelegramUpdateSettlement = {
+    readonly state: 'completed';
+    readonly at: number;
+} | {
+    readonly state: 'failed';
+    readonly at: number;
+    readonly retryAt: number;
+    readonly error: string;
+} | {
+    readonly state: 'abandoned';
+    readonly at: number;
+    readonly error: string;
+};
+export interface TelegramUpdateClaimOptions {
+    readonly now: number;
+    readonly leaseUntil: number;
+    readonly maxAttempts: number;
+}
+export interface TelegramUpdateDueQuery {
+    readonly now: number;
+    /** A `pending` record is due once received at or before this — its own process had its chance. */
+    readonly pendingBefore: number;
+    readonly limit: number;
+}
+export interface StoredTelegramUpdate {
+    readonly updateId: number;
+    readonly body: string;
+}
+export interface TelegramUpdateStore {
+    /** Record a received update as `pending`; `false` when this `update_id` is already recorded. */
+    add(update: StoredTelegramUpdate & {
+        readonly receivedAt: number;
+    }): Promise<boolean>;
+    /** Take a claimable update for one attempt; its number, or `undefined` when not taken. */
+    claim(updateId: number, options: TelegramUpdateClaimOptions): Promise<number | undefined>;
+    /** Extend the lease of this attempt; `false` when the attempt no longer holds the update. */
+    renew(updateId: number, attempt: number, leaseUntil: number): Promise<boolean>;
+    /** End this attempt; ignored when the attempt no longer holds the update. */
+    settle(updateId: number, attempt: number, settlement: TelegramUpdateSettlement): Promise<void>;
+    /** Claimable updates in `update_id` order. */
+    due(query: TelegramUpdateDueQuery): Promise<readonly StoredTelegramUpdate[]>;
+    /** Forget `completed` and `abandoned` updates settled before `before`; how many were forgotten. */
+    prune(before: number): Promise<number>;
+}
+/**
+ * A store in this process's memory — for tests, and for a bot that accepts
+ * losing what was received but not handled when it restarts.
+ */
+export declare function memoryTelegramUpdateStore(): TelegramUpdateStore;
+//# sourceMappingURL=update-store.d.ts.map

package/dist/telegram/update-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"update-store.d.ts","sourceRoot":"","sources":["../../src/telegram/update-store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,MAAM,MAAM,mBAAmB,GAC3B,SAAS,GACT,YAAY,GACZ,QAAQ,GACR,WAAW,GACX,WAAW,CAAC;AAEhB,MAAM,MAAM,wBAAwB,GAChC;IAAE,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAC;IAAC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;CAAE,GACpD;IACE,QAAQ,CAAC,KAAK,EAAE,QAAQ,CAAC;IACzB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB,GACD;IAAE,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAC;IAAC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AAEjF,MAAM,WAAW,0BAA0B;IACzC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;CAC9B;AAED,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,kGAAkG;IAClG,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,mBAAmB;IAClC,gGAAgG;IAChG,GAAG,CAAC,MAAM,EAAE,oBAAoB,GAAG;QAAE,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACtF,0FAA0F;IAC1F,KAAK,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,0BAA0B,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAAC;IAC1F,6FAA6F;IAC7F,KAAK,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAC/E,6EAA6E;IAC7E,MAAM,CACJ,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,wBAAwB,GACnC,OAAO,CAAC,IAAI,CAAC,CAAC;IACjB,8CAA8C;IAC9C,GAAG,CAAC,KAAK,EAAE,sBAAsB,GAAG,OAAO,CAAC,SAAS,oBAAoB,EAAE,CAAC,CAAC;IAC7E,mGAAmG;IACnG,KAAK,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;CACxC;AAsBD;;;GAGG;AACH,wBAAgB,yBAAyB,IAAI,mBAAmB,CAsE/D"}

package/dist/telegram/webhook.d.ts

@@ -0,0 +1,105 @@
+/**
+ * A bot's webhook: one place in all of Telegram, and who may take it.
+ *
+ * `setWebhook` moves a bot's updates without asking whose they were. A process
+ * started anywhere with the production token — a developer's machine, a
+ * staging host, a rehearsal — takes the production bot with one call, and the
+ * production process simply stops hearing from Telegram. So a claim sets the
+ * webhook only where it already points here, or where the caller named the
+ * current owner's host as the one it takes over from (`'none'` when there is no
+ * webhook — a bot on long polling is somebody's bot too).
+ *
+ * "Here" is the address *and* the secret. Telegram never returns the secret,
+ * so the address carries a tag derived from it: an `owner` query parameter
+ * holding an HMAC of the secret. A process with the production address but a
+ * different secret has a different address and is refused, instead of quietly
+ * installing its secret and leaving production answering 403 to every update.
+ * Routers match the path, which the tag leaves alone; the secret cannot be
+ * recovered from it. Errors and reports name hosts only — a foreign webhook's
+ * path may itself be a secret.
+ */
+/** `takeoverFrom` when there is no webhook to take over — the bot polls, or is new. */
+export declare const TELEGRAM_WEBHOOK_NONE = "none";
+export interface TelegramWebhookConfig {
+    readonly token: string;
+    /** Where Telegram should post updates, without the owner tag. */
+    readonly url: string;
+    /** Telegram's `secret_token`: 1–256 of `A-Z a-z 0-9 _ -`. */
+    readonly secret: string;
+    /** A local Bot API server. Default: Telegram's. */
+    readonly apiRoot?: string;
+    readonly fetch?: typeof fetch;
+    readonly signal?: AbortSignal;
+}
+export interface ClaimTelegramWebhookConfig extends TelegramWebhookConfig {
+    /**
+     * The host the webhook may be taken from — the current owner's, as the
+     * refusal names it — or `'none'` to set one where there is none. Set it for
+     * one switch and remove it: left in place it is a standing permission.
+     */
+    readonly takeoverFrom?: string;
+    /** Telegram's `allowed_updates`. Default: whatever the webhook had. */
+    readonly allowedUpdates?: readonly string[];
+    /** Telegram's `max_connections`, 1–100. */
+    readonly maxConnections?: number;
+    /** Default `false`: updates waiting for the previous owner are this owner's now. */
+    readonly dropPendingUpdates?: boolean;
+}
+export interface TelegramWebhookClaim {
+    /** The address set, owner tag included. */
+    readonly url: string;
+    /** The host it was taken over from; absent when it was already this one's. */
+    readonly takenFrom?: string;
+    readonly pendingUpdates: number;
+}
+export type TelegramWebhookRefusal = 
+/** Another host holds the webhook. */
+'owned-elsewhere'
+/** This address holds it, registered with another secret. */
+ | 'other-secret'
+/** Telegram accepted `setWebhook` but reports another address after it. */
+ | 'not-confirmed';
+export declare class TelegramWebhookClaimError extends Error {
+    readonly reason: TelegramWebhookRefusal;
+    /** Where the webhook points, as a host; `'none'` when nowhere. */
+    readonly ownerHost: string;
+    constructor(reason: TelegramWebhookRefusal, ownerHost: string);
+}
+export interface TelegramWebhookState {
+    /** The webhook points to this address with this secret. */
+    readonly owned: boolean;
+    readonly ownerHost: string;
+    readonly pendingUpdates: number;
+    /** Telegram's last failure to deliver, if it reported one. */
+    readonly lastError?: {
+        readonly at: number;
+        readonly message: string;
+    };
+}
+/** The address with its owner tag: the same for every process with this secret. */
+export declare function telegramWebhookUrl(url: string, secret: string): Promise<string>;
+/**
+ * Set the webhook if it is this process's to set, and confirm Telegram holds
+ * it. Refused — without `setWebhook` — when another host or another secret
+ * holds it and `takeoverFrom` does not name that holder.
+ */
+export declare function claimTelegramWebhook(config: ClaimTelegramWebhookConfig): Promise<TelegramWebhookClaim>;
+/**
+ * Whether the webhook still points here. A webhook moved to another host, or
+ * re-registered with another secret, stops this process hearing from Telegram
+ * without any error of its own — a periodic check is how it is noticed.
+ */
+export declare function checkTelegramWebhook(config: TelegramWebhookConfig): Promise<TelegramWebhookState>;
+/** What becomes of an update body: recorded, seen before, or not an update. */
+export type TelegramUpdateAcceptance = 'accepted' | 'duplicate' | 'invalid';
+export interface ReceiveTelegramWebhookOptions {
+    readonly secret: string;
+    /** Records the update; answered to Telegram as soon as this resolves. */
+    readonly accept: (body: string) => Promise<TelegramUpdateAcceptance>;
+}
+/**
+ * Answer one webhook request: 403 without this secret, 400 for a body that is
+ * not an update, 200 once the update is recorded — before it is handled.
+ */
+export declare function receiveTelegramWebhook(request: Request, options: ReceiveTelegramWebhookOptions): Promise<Response>;
+//# sourceMappingURL=webhook.d.ts.map

package/dist/telegram/webhook.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"webhook.d.ts","sourceRoot":"","sources":["../../src/telegram/webhook.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAWH,uFAAuF;AACvF,eAAO,MAAM,qBAAqB,SAAS,CAAC;AAE5C,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,iEAAiE;IACjE,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,6DAA6D;IAC7D,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,mDAAmD;IACnD,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,KAAK,CAAC;IAC9B,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC;CAC/B;AAED,MAAM,WAAW,0BAA2B,SAAQ,qBAAqB;IACvE;;;;OAIG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B,uEAAuE;IACvE,QAAQ,CAAC,cAAc,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC5C,2CAA2C;IAC3C,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;IACjC,oFAAoF;IACpF,QAAQ,CAAC,kBAAkB,CAAC,EAAE,OAAO,CAAC;CACvC;AAED,MAAM,WAAW,oBAAoB;IACnC,2CAA2C;IAC3C,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,8EAA8E;IAC9E,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;CACjC;AAED,MAAM,MAAM,sBAAsB;AAChC,sCAAsC;AACpC,iBAAiB;AACnB,6DAA6D;GAC3D,cAAc;AAChB,2EAA2E;GACzE,eAAe,CAAC;AAEpB,qBAAa,yBAA0B,SAAQ,KAAK;IAClD,QAAQ,CAAC,MAAM,EAAE,sBAAsB,CAAC;IACxC,kEAAkE;IAClE,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAE3B,YAAY,MAAM,EAAE,sBAAsB,EAAE,SAAS,EAAE,MAAM,EAa5D;CACF;AAED,MAAM,WAAW,oBAAoB;IACnC,2DAA2D;IAC3D,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,8DAA8D;IAC9D,QAAQ,CAAC,SAAS,CAAC,EAAE;QAAE,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;CACxE;AAcD,mFAAmF;AACnF,wBAAsB,kBAAkB,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAUrF;AA+BD;;;;GAIG;AACH,wBAAsB,oBAAoB,CACxC,MAAM,EAAE,0BAA0B,GACjC,OAAO,CAAC,oBAAoB,CAAC,CAgC/B;AAED;;;;GAIG;AACH,wBAAsB,oBAAoB,CACxC,MAAM,EAAE,qBAAqB,GAC5B,OAAO,CAAC,oBAAoB,CAAC,CAS/B;AAED,+EAA+E;AAC/E,MAAM,MAAM,wBAAwB,GAAG,UAAU,GAAG,WAAW,GAAG,SAAS,CAAC;AAE5E,MAAM,WAAW,6BAA6B;IAC5C,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,yEAAyE;IACzE,QAAQ,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,wBAAwB,CAAC,CAAC;CACtE;AAED;;;GAGG;AACH,wBAAsB,sBAAsB,CAC1C,OAAO,EAAE,OAAO,EAChB,OAAO,EAAE,6BAA6B,GACrC,OAAO,CAAC,QAAQ,CAAC,CAUnB"}

package/dist/tools/cli/args-fields.d.ts

@@ -20,6 +20,14 @@ export interface FieldInfo {
  */
 export declare function describeSchemaFields(schema: z.ZodType | undefined): Map<string, FieldInfo>;
 /** Strict boolean for a RESERVED option — an unrecognised value is a usage error, never a silent `true`. */
+/**
+ * The token after a bare boolean flag, when it is the flag's value: exactly
+ * `true` or `false` — `--verbose false` is a common habit, and reading it as
+ * "on, plus a positional `false`" silently does the opposite of what was said.
+ * Only those two words: `1`, `yes` or `no` there stay positionals, since a
+ * flag followed by an ordinary value must not swallow it.
+ */
+export declare function separateBoolValue(next: string | undefined): boolean | undefined;
 /** True for a value the reserved-boolean grammar already claims. */
 export declare function isReservedBoolWord(value: string): boolean;
 export declare function parseReservedBool(name: string, value: string): boolean;

package/dist/tools/cli/args-fields.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"args-fields.d.ts","sourceRoot":"","sources":["../../../src/tools/cli/args-fields.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAKxB,MAAM,MAAM,SAAS,GACjB,SAAS,GACT,QAAQ,GACR,QAAQ,GACR,MAAM,GACN,QAAQ,GACR,MAAM,GACN,OAAO,GACP,QAAQ,GACR,OAAO,CAAC;AAEZ,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,SAAS,CAAC;IAChB,uEAAuE;IACvE,WAAW,CAAC,EAAE,SAAS,CAAC;IACxB,iFAAiF;IACjF,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AA6ED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,CAAC,CAAC,OAAO,GAAG,SAAS,GAAG,GAAG,CAAC,MAAM,EAAE,SAAS,CAAC,CAI1F;AAKD,4GAA4G;AAC5G,oEAAoE;AACpE,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAGzD;AAED,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAKtE;AA8BD,qFAAqF;AACrF,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAKlD;AAuCD,gFAAgF;AAChF,wBAAgB,WAAW,CACzB,IAAI,EAAE,SAAS,GAAG,SAAS,EAC3B,MAAM,EAAE,MAAM,EAAE,EAChB,KAAK,EAAE,MAAM,GACZ,OAAO,CAaT;AAED,wBAAgB,SAAS,CACvB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/B,IAAI,EAAE,MAAM,EAAE,EACd,KAAK,EAAE,OAAO,GACb,IAAI,CAsBN"}
+{"version":3,"file":"args-fields.d.ts","sourceRoot":"","sources":["../../../src/tools/cli/args-fields.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAKxB,MAAM,MAAM,SAAS,GACjB,SAAS,GACT,QAAQ,GACR,QAAQ,GACR,MAAM,GACN,QAAQ,GACR,MAAM,GACN,OAAO,GACP,QAAQ,GACR,OAAO,CAAC;AAEZ,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,SAAS,CAAC;IAChB,uEAAuE;IACvE,WAAW,CAAC,EAAE,SAAS,CAAC;IACxB,iFAAiF;IACjF,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AA6ED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,CAAC,CAAC,OAAO,GAAG,SAAS,GAAG,GAAG,CAAC,MAAM,EAAE,SAAS,CAAC,CAI1F;AAKD,4GAA4G;AAC5G;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,GAAG,SAAS,CAI/E;AAED,oEAAoE;AACpE,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAGzD;AAED,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAKtE;AA8BD,qFAAqF;AACrF,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAKlD;AAuCD,gFAAgF;AAChF,wBAAgB,WAAW,CACzB,IAAI,EAAE,SAAS,GAAG,SAAS,EAC3B,MAAM,EAAE,MAAM,EAAE,EAChB,KAAK,EAAE,MAAM,GACZ,OAAO,CAaT;AAED,wBAAgB,SAAS,CACvB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/B,IAAI,EAAE,MAAM,EAAE,EACd,KAAK,EAAE,OAAO,GACb,IAAI,CAsBN"}

package/dist/tools/cli/args-route.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"args-route.d.ts","sourceRoot":"","sources":["../../../src/tools/cli/args-route.ts"],"names":[],"mappings":"AAOA;;;;;;;;;GASG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAEpD;AAED;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAEtD;AAGD,eAAO,MAAM,YAAY,aAA6D,CAAC;AAEvF,eAAO,MAAM,oBAAoB,aAA+C,CAAC;AAEjF,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,OAAO,CAAC;IAChB,UAAU,CAAC,EAAE,SAAS,GAAG,OAAO,CAAC;CAClC;AAED,sFAAsF;AACtF,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,MAAM,GAAG,kBAAkB,GAAG,SAAS,CAcrF;AAED,MAAM,WAAW,YAAY;IAC3B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,YAAY,EAAE,OAAO,CAAC;IACtB,OAAO,EAAE,OAAO,CAAC;IACjB,mFAAmF;IACnF,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AA+BD,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,cAAc,CAAC,EAAE,MAAM,GAAG,YAAY,CA6GlF"}
+{"version":3,"file":"args-route.d.ts","sourceRoot":"","sources":["../../../src/tools/cli/args-route.ts"],"names":[],"mappings":"AAOA;;;;;;;;;GASG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAEpD;AAED;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAEtD;AAGD,eAAO,MAAM,YAAY,aAA6D,CAAC;AAEvF,eAAO,MAAM,oBAAoB,aAA+C,CAAC;AAEjF,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,OAAO,CAAC;IAChB,UAAU,CAAC,EAAE,SAAS,GAAG,OAAO,CAAC;CAClC;AAED,sFAAsF;AACtF,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,MAAM,GAAG,kBAAkB,GAAG,SAAS,CAcrF;AAED,MAAM,WAAW,YAAY;IAC3B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,YAAY,EAAE,OAAO,CAAC;IACtB,OAAO,EAAE,OAAO,CAAC;IACjB,mFAAmF;IACnF,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AA+BD,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,cAAc,CAAC,EAAE,MAAM,GAAG,YAAY,CAuHlF"}

package/dist/tools/cli/args.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"args.d.ts","sourceRoot":"","sources":["../../../src/tools/cli/args.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AACH,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAgB7B,OAAO,EAAE,KAAK,aAAa,EAAkB,MAAM,aAAa,CAAC;AAGjE,yEAAyE;AACzE,MAAM,WAAW,aAAa;IAC5B,sEAAsE;IACtE,IAAI,EAAE,OAAO,CAAC;IACd,iEAAiE;IACjE,IAAI,EAAE,OAAO,CAAC;IACd,8DAA8D;IAC9D,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,wEAAwE;IACxE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,yDAAyD;IACzD,KAAK,EAAE,OAAO,CAAC;IACf,qEAAqE;IACrE,MAAM,EAAE,OAAO,CAAC;IAChB,qDAAqD;IACrD,IAAI,EAAE,OAAO,CAAC;IACd,0FAA0F;IAC1F,IAAI,CAAC,EAAE,aAAa,CAAC;CACtB;AAED,MAAM,WAAW,aAAa;IAC5B,mEAAmE;IACnE,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClC,+BAA+B;IAC/B,OAAO,EAAE,aAAa,CAAC;CACxB;AAkRD,wBAAgB,YAAY,CAC1B,IAAI,EAAE,MAAM,EAAE,EACd,MAAM,EAAE,CAAC,CAAC,OAAO,GAAG,SAAS,EAC7B,MAAM,GAAE;IACN,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,WAAW,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAChC,aAAa,CAAC,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC5C,WAAW,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC5B,GACL,aAAa,CAUf;AAED,iFAAiF;AACjF,MAAM,WAAW,qBAAqB;IACpC,0EAA0E;IAC1E,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,wEAAwE;IACxE,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAClC;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,uBAAuB,CACrC,IAAI,EAAE,SAAS,MAAM,EAAE,EACvB,MAAM,EAAE,CAAC,CAAC,SAAS,GAAG,SAAS,GAC9B,qBAAqB,CAgDvB"}
+{"version":3,"file":"args.d.ts","sourceRoot":"","sources":["../../../src/tools/cli/args.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AACH,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAiB7B,OAAO,EAAE,KAAK,aAAa,EAAkB,MAAM,aAAa,CAAC;AAGjE,yEAAyE;AACzE,MAAM,WAAW,aAAa;IAC5B,sEAAsE;IACtE,IAAI,EAAE,OAAO,CAAC;IACd,iEAAiE;IACjE,IAAI,EAAE,OAAO,CAAC;IACd,8DAA8D;IAC9D,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,wEAAwE;IACxE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,yDAAyD;IACzD,KAAK,EAAE,OAAO,CAAC;IACf,qEAAqE;IACrE,MAAM,EAAE,OAAO,CAAC;IAChB,qDAAqD;IACrD,IAAI,EAAE,OAAO,CAAC;IACd,0FAA0F;IAC1F,IAAI,CAAC,EAAE,aAAa,CAAC;CACtB;AAED,MAAM,WAAW,aAAa;IAC5B,mEAAmE;IACnE,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClC,+BAA+B;IAC/B,OAAO,EAAE,aAAa,CAAC;CACxB;AA4RD,wBAAgB,YAAY,CAC1B,IAAI,EAAE,MAAM,EAAE,EACd,MAAM,EAAE,CAAC,CAAC,OAAO,GAAG,SAAS,EAC7B,MAAM,GAAE;IACN,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,WAAW,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAChC,aAAa,CAAC,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC5C,WAAW,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC5B,GACL,aAAa,CAUf;AAED,iFAAiF;AACjF,MAAM,WAAW,qBAAqB;IACpC,0EAA0E;IAC1E,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,wEAAwE;IACxE,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAClC;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,uBAAuB,CACrC,IAAI,EAAE,SAAS,MAAM,EAAE,EACvB,MAAM,EAAE,CAAC,CAAC,SAAS,GAAG,SAAS,GAC9B,qBAAqB,CAkDvB"}

package/dist/tools/cli/help.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"help.d.ts","sourceRoot":"","sources":["../../../src/tools/cli/help.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,eAAe,EAAoB,MAAM,+BAA+B,CAAC;AAEvF,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,UAAU,CAAC;AA6DvD;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAC5B,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE,sBAAsB,CAAC,EAC7C,MAAM,EAAE,MAAM,GACb,GAAG,CAAC,MAAM,EAAE,sBAAsB,CAAC,CASrC;AAED,wBAAgB,aAAa,CAAC,KAAK,EAAE;IACnC,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE,sBAAsB,CAAC,CAAC;IAC9C,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,kBAAkB,EAAE,SAAS,eAAe,EAAE,CAAC;IAC/C,wEAAwE;IACxE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,mEAAmE;IACnE,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,GAAG,MAAM,CAqCT;AAED,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,sBAAsB,EAClC,kBAAkB,GAAE,SAAS,eAAe,EAAO,GAClD,MAAM,CAsDR"}
+{"version":3,"file":"help.d.ts","sourceRoot":"","sources":["../../../src/tools/cli/help.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,eAAe,EAAoB,MAAM,+BAA+B,CAAC;AAEvF,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,UAAU,CAAC;AA6DvD;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAC5B,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE,sBAAsB,CAAC,EAC7C,MAAM,EAAE,MAAM,GACb,GAAG,CAAC,MAAM,EAAE,sBAAsB,CAAC,CASrC;AAED,wBAAgB,aAAa,CAAC,KAAK,EAAE;IACnC,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE,sBAAsB,CAAC,CAAC;IAC9C,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,kBAAkB,EAAE,SAAS,eAAe,EAAE,CAAC;IAC/C,wEAAwE;IACxE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,mEAAmE;IACnE,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,GAAG,MAAM,CAqCT;AAED,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,sBAAsB,EAClC,kBAAkB,GAAE,SAAS,eAAe,EAAO,GAClD,MAAM,CA6DR"}

package/llms/application.2.txt

@@ -11,6 +11,31 @@ Parts of this slice:
 # Guide: Managed application kernel  (docs/guide/application-kernel.md)  (continued)
 ==============================================================================
 
+## Recovering change subscriptions
+
+`changeSubscriptionResource` is an optional resource over a consumer-owned driver.
+It uses a finite declared key set, subscribes before reading, reconciles after
+reconnect and periodically repairs lost hints. `reconcileIntervalMs` is explicit;
+notifications alone cannot prove freshness. Within a key, hints coalesce into one
+trailing read and a failed read retries with backoff. Use the supplied
+`context.commit(() => publish(value))` after awaits to reject an obsolete connection.
+
+Drivers implement `connect(signal)` and return `subscribe({ signal, hint,
+disconnected })` plus `close()`. Subscribe must establish the notification boundary
+before resolving. A database LISTEN driver owns its connection, channels, decoding
+and transaction ordering; no SQL or database driver is included here. The resource
+owns reconnect, deadlines and shutdown. Drivers must honor abort. If one ignores it,
+its slot remains occupied until settlement; deadlines cannot safely manufacture
+successful cleanup or permit an overlapping connection.
+
+For watched reads, set `reconcileIntervalMs` on the existing `createWatchHub` rather
+than building a second read loop. Its per-key machinery is shared with managed
+subscriptions. Limits default to 1024 sources and 1024 subscribers per hub; set
+explicit finite values for larger workloads. Supply a server-verified admission
+scope to `attach` and abort it on logout, permission revocation or session replacement.
+The read callback receives the trusted scope as its third argument. A client owner
+ID in arguments is not authentication.
+
 ## Multi-action notification delivery
 
 Opt into `delivery: { version, actions, project }` on `createNotificationOutbox`.
@@ -328,7 +353,7 @@ cutovers are covered by the executable
 | `LifecycleRunSchema` / `LifecycleRun` / `LifecycleStateSchema` / `LifecycleState` / `LifecycleTerminationSchema` / `LifecycleTermination` | schema / _type_ | versioned process-run state — open (`active`, `draining` with `unavailableAt`) and ended (`clean`, `forced`, `startup-failed`, `hot-reload`, `abnormal`) |
 | `PreviousExitSchema` / `PreviousExit` / `StartFact` / `ReadyFact` / `DrainingFact` / `ShutdownFact` / `ProcessLifecycleFact` | schema / _type_ | first-boot, hot-reload, clean, forced, startup-failed, handoff and abnormal lifecycle facts; `processGapMs` on start, `downtimeMs` (unavailable → ready) on ready |
 | `transitionProcessStart` / `transitionProcessReady` / `transitionProcessDraining` / `transitionProcessShutdown` | function | pure idempotent runId+pid-owned transitions |
-| `LifecycleTransition` / `TransitionStartInput` / `TransitionRunInput` / `TransitionShutdownInput` / `SameVersionOverlap` | _type_ | pure transition inputs (`TransitionRunInput` for ready and draining, extended with `forced` for shutdown), the same-build overlap policy (`abnormal` default / `handoff`) and state+fact result |
+| `LifecycleTransition` / `TransitionStartInput` / `TransitionRunInput` / `TransitionShutdownInput` / `SameVersionOverlap` / `VersionChangeOverlap` | _type_ | pure transition inputs (`TransitionRunInput` for ready and draining, extended with `forced` for shutdown), the same-build overlap policy (`abnormal` default / `handoff`), the version-change overlap policy (`handoff` default / `abnormal`) and state+fact result |
 | `lifecycleLedgerResource` / `LifecycleLedgerResource` / `LifecycleLedgerResourceConfig` | function / _type_ | managed-resource adapter that records start, readiness, admission stop (draining) and shutdown |
 | `createNotificationOutbox` / `NotificationOutbox` / `NotificationOutboxConfig` | function / _type_ | bounded at-least-once queue with durable claims, leases, retries and supersede |
 | `NotificationOutboxItem` / `NotificationOutboxReceipt` / `NotificationOutboxState` / `NotificationSend` / `NotificationFailureClassification` / `DroppedNotification` / `EnqueueNotification` | _type_ | versioned queue records, stable send identity and delivery decisions |