stitchkit 0.95.3 → 0.96.0

package/dist/entrypoints/testing.js

@@ -1,6 +1,6 @@
 import {
   createApplication
-} from "../index-w906953s.js";
+} from "../index-5qn1kx34.js";
 import"../index-3gye9wzb.js";
 import"../index-2k4yrqkc.js";
 import"../index-3z73fh2c.js";

package/dist/{index-w906953s.js → index-5qn1kx34.js}

@@ -288,6 +288,50 @@ function waitForPending(state) {
     return Promise.resolve();
   return new Promise((resolve) => state.pendingWaiters.add(resolve));
 }
+function acquireWhenAccepting(state, signal) {
+  return new Promise((resolve, reject) => {
+    let scheduled = false;
+    let settled = false;
+    const finish = () => {
+      settled = true;
+      state.listeners.delete(onChange);
+      signal.removeEventListener("abort", attempt);
+    };
+    function attempt() {
+      if (settled)
+        return true;
+      if (signal.aborted) {
+        finish();
+        reject(signal.reason);
+        return true;
+      }
+      if (state.shutdownRequested || state.lifecycle === "failed" || state.lifecycle === "stopped") {
+        finish();
+        reject(new ApplicationAdmissionError);
+        return true;
+      }
+      const lease = acquire(state);
+      if (!lease)
+        return false;
+      finish();
+      resolve(lease);
+      return true;
+    }
+    function onChange() {
+      if (scheduled)
+        return;
+      scheduled = true;
+      queueMicrotask(() => {
+        scheduled = false;
+        attempt();
+      });
+    }
+    if (attempt())
+      return;
+    state.listeners.add(onChange);
+    signal.addEventListener("abort", attempt, { once: true });
+  });
+}
 
 // src/application/kernel-resource-context.ts
 function contextFor(state, record, options = {}) {
@@ -299,6 +343,10 @@ function contextFor(state, record, options = {}) {
       forceDeadlineAt: options.forceDeadlineAt
     },
     now: () => performance.now(),
+    admission: {
+      acquire: () => acquire(state),
+      acquireWhenAccepting: (signal) => acquireWhenAccepting(state, signal)
+    },
     use(resource) {
       const dependencyId = resource?.id;
       if (typeof dependencyId !== "string" || dependencyId.length === 0) {

package/dist/observability/json-logger.d.ts

@@ -0,0 +1,38 @@
+import type { StitchLogger } from '../internal/logger.js';
+import { type BoundedLoggerOptions } from './bounded-logger.js';
+/**
+ * A process journal: one JSON object per line on standard output.
+ *
+ * A long-running process without a request — a bot, a worker — had no journal
+ * of its own here, so each one chose: a hand-written ndjson writer that cut the
+ * stack, `console.log` strings, or pino, where an error logged under any key but
+ * `err` became `"error":{}` and a production startup failure had to be
+ * reproduced by hand to learn its cause.
+ *
+ * The line is pino's shape on purpose — numeric `level`, `time` in epoch
+ * milliseconds, `msg` — so a supervisor that already recognises
+ * `"level":50` as an error, and `pino-pretty` on a developer's terminal, read
+ * it unchanged. What pino does not do, this does: every value passes through
+ * `createBoundedLogger`, so an `Error` in *any* field is written with its name,
+ * message, stack and cause, secrets are masked, and one line stays bounded.
+ */
+/** pino's numbers, which is the contract a line reader matches on. */
+export declare const JSON_LOG_LEVELS: {
+    readonly debug: 20;
+    readonly info: 30;
+    readonly warn: 40;
+    readonly error: 50;
+};
+export type JsonLogLevel = keyof typeof JSON_LOG_LEVELS;
+export interface JsonLoggerOptions extends Omit<BoundedLoggerOptions, 'sink'> {
+    /** The lowest level written. Default `info`. */
+    readonly level?: JsonLogLevel;
+    /** Fields on every line — the service name, the release. A call's own fields win. */
+    readonly fields?: Readonly<Record<string, unknown>>;
+    /** Where a finished line goes. Default: standard output, newline-terminated. */
+    readonly write?: (line: string) => void;
+    /** Default `Date.now`. */
+    readonly now?: () => number;
+}
+export declare function createJsonLogger(options?: JsonLoggerOptions): StitchLogger;
+//# sourceMappingURL=json-logger.d.ts.map

package/dist/observability/json-logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"json-logger.d.ts","sourceRoot":"","sources":["../../src/observability/json-logger.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AACvD,OAAO,EAAE,KAAK,oBAAoB,EAAuB,MAAM,kBAAkB,CAAC;AAElF;;;;;;;;;;;;;;;GAeG;AAEH,sEAAsE;AACtE,eAAO,MAAM,eAAe;aAAK,KAAK,EAAE,EAAE;aAAE,IAAI,EAAE,EAAE;aAAE,IAAI,EAAE,EAAE;aAAE,KAAK,EAAE,EAAE;CAAW,CAAC;AACrF,MAAM,MAAM,YAAY,GAAG,MAAM,OAAO,eAAe,CAAC;AAExD,MAAM,WAAW,iBAAkB,SAAQ,IAAI,CAAC,oBAAoB,EAAE,MAAM,CAAC;IAC3E,gDAAgD;IAChD,QAAQ,CAAC,KAAK,CAAC,EAAE,YAAY,CAAC;IAC9B,qFAAqF;IACrF,QAAQ,CAAC,MAAM,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IACpD,gFAAgF;IAChF,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IACxC,0BAA0B;IAC1B,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CAC7B;AAeD,wBAAgB,gBAAgB,CAAC,OAAO,GAAE,iBAAsB,GAAG,YAAY,CAgC9E"}

package/dist/telegram/bot-api.d.ts

@@ -0,0 +1,50 @@
+/**
+ * One Bot API call over `fetch`, with no bot library.
+ *
+ * The operator channel and the broadcast send outside any update handler — from
+ * a script, a schedule, a failure observer — where a whole grammY instance is
+ * more than the job needs. What they need is one request whose refusal keeps
+ * Telegram's own structured answer, because `classifyTelegramSendFailure`
+ * reads `error_code` and `parameters.retry_after` before it ever reads prose.
+ */
+/**
+ * The shape of a bot token: the bot's numeric id, a colon, the secret.
+ *
+ * For masking, not for validation — hand it to a logger's
+ * `sensitiveUrlPatterns` and a token inside a URL or an error message is not
+ * written to the journal.
+ */
+export declare const TELEGRAM_BOT_TOKEN_PATTERN: RegExp;
+/** Telegram refused the call. Carries its answer as fields, never the token. */
+export declare class TelegramBotApiError extends Error {
+    readonly method: string;
+    readonly error_code: number;
+    readonly description: string;
+    readonly parameters: {
+        readonly retry_after?: number;
+        readonly migrate_to_chat_id?: number;
+    };
+    constructor(method: string, answer: {
+        error_code: number;
+        description: string;
+        parameters?: TelegramBotApiError['parameters'];
+    });
+}
+export interface TelegramBotApiCall {
+    readonly token: string;
+    readonly method: string;
+    readonly params?: Readonly<Record<string, unknown>>;
+    /** A local Bot API server, e.g. `http://127.0.0.1:8081`. Default: Telegram's. */
+    readonly apiRoot?: string;
+    readonly signal?: AbortSignal;
+    readonly fetch?: typeof fetch;
+}
+/**
+ * Call one Bot API method and return its `result`.
+ *
+ * A refusal throws `TelegramBotApiError`; a transport failure throws an error
+ * whose message names the method and never the URL, since the URL holds the
+ * token.
+ */
+export declare function callTelegramBotApi(call: TelegramBotApiCall): Promise<unknown>;
+//# sourceMappingURL=bot-api.d.ts.map

package/dist/telegram/bot-api.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bot-api.d.ts","sourceRoot":"","sources":["../../src/telegram/bot-api.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH;;;;;;GAMG;AACH,eAAO,MAAM,0BAA0B,QAA8B,CAAC;AAItE,gFAAgF;AAChF,qBAAa,mBAAoB,SAAQ,KAAK;IAC5C,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,UAAU,EAAE;QAAE,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,kBAAkB,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAE7F,YACE,MAAM,EAAE,MAAM,EACd,MAAM,EAAE;QACN,UAAU,EAAE,MAAM,CAAC;QACnB,WAAW,EAAE,MAAM,CAAC;QACpB,UAAU,CAAC,EAAE,mBAAmB,CAAC,YAAY,CAAC,CAAC;KAChD,EAQF;CACF;AAED,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IACpD,iFAAiF;IACjF,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC;IAC9B,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,KAAK,CAAC;CAC/B;AAQD;;;;;;GAMG;AACH,wBAAsB,kBAAkB,CAAC,IAAI,EAAE,kBAAkB,GAAG,OAAO,CAAC,OAAO,CAAC,CAuCnF"}

package/dist/telegram/broadcast-state.d.ts

@@ -0,0 +1,67 @@
+/**
+ * The durable half of a broadcast: who it is for, and what happened to each.
+ *
+ * Two files per broadcast name. The recipients are written once, atomically,
+ * the first time the broadcast runs — the audience of a resumed broadcast is
+ * the audience it started with, not whoever matches the query today. Progress
+ * is an append-only journal: a line before each send and a line after it, so
+ * recording one send costs one short append instead of rewriting a state file
+ * that grows with the audience.
+ *
+ * The line before the send is what makes a crash honest. A recipient whose
+ * last line says `sending` may or may not have received the message; a resume
+ * records them as `uncertain` and does not send again, because a second copy
+ * of a broadcast is the failure a subscriber notices.
+ */
+import { z } from 'zod';
+export declare const TelegramBroadcastOutcomeSchema: z.ZodEnum<{
+    delivered: "delivered";
+    failed: "failed";
+    uncertain: "uncertain";
+    unreachable: "unreachable";
+}>;
+export type TelegramBroadcastOutcome = z.infer<typeof TelegramBroadcastOutcomeSchema>;
+declare const ChatIdSchema: z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>;
+export type TelegramBroadcastRecipient = z.infer<typeof ChatIdSchema>;
+declare const JournalLineSchema: z.ZodUnion<readonly [z.ZodObject<{
+    i: z.ZodNumber;
+    s: z.ZodEnum<{
+        released: "released";
+        sending: "sending";
+    }>;
+}, z.core.$strict>, z.ZodObject<{
+    i: z.ZodNumber;
+    o: z.ZodEnum<{
+        delivered: "delivered";
+        failed: "failed";
+        uncertain: "uncertain";
+        unreachable: "unreachable";
+    }>;
+    r: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>]>;
+type JournalLine = z.infer<typeof JournalLineSchema>;
+/** Per recipient index: the outcome, or `sending` for a send whose end is unknown. */
+export type BroadcastProgress = Map<number, TelegramBroadcastOutcome | 'sending'>;
+export declare function assertBroadcastName(name: string): void;
+export interface BroadcastFiles {
+    readonly recipients: string;
+    readonly journal: string;
+    readonly lock: string;
+}
+export declare function broadcastFiles(directory: string, name: string): BroadcastFiles;
+export declare function readRecipients(files: BroadcastFiles): Promise<TelegramBroadcastRecipient[] | null>;
+export declare function writeRecipients(files: BroadcastFiles, recipients: readonly TelegramBroadcastRecipient[]): Promise<void>;
+/**
+ * Replay the journal. A torn last line — the process died mid-append — is
+ * skipped; every complete line before it stands.
+ */
+export declare function readProgress(files: BroadcastFiles): Promise<BroadcastProgress>;
+export declare function appendJournal(files: BroadcastFiles, line: JournalLine): Promise<void>;
+/**
+ * One runner per broadcast name. Two would each read the same pending
+ * recipients and send them twice. A lock left by a process that is gone is
+ * taken over.
+ */
+export declare function lockBroadcast(directory: string, files: BroadcastFiles): Promise<() => Promise<void>>;
+export {};
+//# sourceMappingURL=broadcast-state.d.ts.map

package/dist/telegram/broadcast-state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"broadcast-state.d.ts","sourceRoot":"","sources":["../../src/telegram/broadcast-state.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAIH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,eAAO,MAAM,8BAA8B;;;;;EAKzC,CAAC;AACH,MAAM,MAAM,wBAAwB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,8BAA8B,CAAC,CAAC;AAEtF,QAAA,MAAM,YAAY,iDAAyD,CAAC;AAC5E,MAAM,MAAM,0BAA0B,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,YAAY,CAAC,CAAC;AAItE,QAAA,MAAM,iBAAiB;;;;;;;;;;;;;;;oBASrB,CAAC;AACH,KAAK,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAErD,sFAAsF;AACtF,MAAM,MAAM,iBAAiB,GAAG,GAAG,CAAC,MAAM,EAAE,wBAAwB,GAAG,SAAS,CAAC,CAAC;AAIlF,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAMtD;AAKD,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED,wBAAgB,cAAc,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,cAAc,CAM9E;AAED,wBAAsB,cAAc,CAClC,KAAK,EAAE,cAAc,GACpB,OAAO,CAAC,0BAA0B,EAAE,GAAG,IAAI,CAAC,CAO9C;AAED,wBAAsB,eAAe,CACnC,KAAK,EAAE,cAAc,EACrB,UAAU,EAAE,SAAS,0BAA0B,EAAE,GAChD,OAAO,CAAC,IAAI,CAAC,CAIf;AAED;;;GAGG;AACH,wBAAsB,YAAY,CAAC,KAAK,EAAE,cAAc,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAsBpF;AAED,wBAAgB,aAAa,CAAC,KAAK,EAAE,cAAc,EAAE,IAAI,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAErF;AAWD;;;;GAIG;AACH,wBAAsB,aAAa,CACjC,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,cAAc,GACpB,OAAO,CAAC,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC,CAkB9B"}

package/dist/telegram/broadcast.d.ts

@@ -0,0 +1,93 @@
+/**
+ * A broadcast that survives its own process.
+ *
+ * Two bots carried the same broadcast subsystem — three files byte-identical —
+ * and inside it their own list of refusal phrases and their own single retry
+ * on 429. This is that subsystem once: the application says who and how one
+ * message is sent; the runner owns the pacing, the retries Telegram asks for,
+ * the difference between "not this recipient" and "not this message", and the
+ * state that lets a broadcast stopped by a crash, a deploy or Ctrl-C continue
+ * where it was without writing twice to anyone.
+ *
+ * It is a function, not a resource. A broadcast is a job with an end: run from
+ * a script it takes the process's signal; run inside a live application it
+ * takes the application's, and admission is the caller's to hold around it.
+ */
+import { type TelegramBroadcastRecipient } from './broadcast-state.js';
+import { type TelegramSendFailure } from './send-failure.js';
+export type { TelegramBroadcastOutcome, TelegramBroadcastRecipient } from './broadcast-state.js';
+export interface TelegramBroadcastSend {
+    readonly recipient: TelegramBroadcastRecipient;
+    /** 1 for the first try of this recipient in this run. */
+    readonly attempt: number;
+}
+export interface TelegramBroadcastConfig {
+    /** The broadcast's identity: running the same name again resumes it. `[A-Za-z0-9._-]`. */
+    readonly name: string;
+    /** Where its state lives — a state root, never the release tree. Absolute. */
+    readonly directory: string;
+    /**
+     * The audience, read once: on the first run it is written down, and every
+     * resumed run sends to that list. Duplicates are sent once.
+     */
+    readonly recipients: () => Iterable<TelegramBroadcastRecipient> | AsyncIterable<TelegramBroadcastRecipient> | Promise<Iterable<TelegramBroadcastRecipient>>;
+    /** Send the message to one recipient; throw Telegram's refusal as it came. */
+    readonly send: (send: TelegramBroadcastSend) => Promise<unknown>;
+    /** Sends started per second. Default 25, under Telegram's 30 for one bot. */
+    readonly ratePerSecond?: number;
+    /** Tries of one recipient on a retryable refusal before it is `failed`. Default 5. */
+    readonly maxAttempts?: number;
+    /** Count what would be sent and send nothing; no state is written. */
+    readonly dryRun?: boolean;
+    /** Stops between sends — the send in flight is finished and recorded first. */
+    readonly signal?: AbortSignal;
+    /** At the start, every `progressEveryMs`, and at the end. */
+    readonly onProgress?: (report: TelegramBroadcastReport) => void;
+    /** Default 10 000. */
+    readonly progressEveryMs?: number;
+    readonly sleep?: (milliseconds: number) => Promise<void>;
+    readonly now?: () => number;
+}
+/**
+ * - `finished` — nobody is left.
+ * - `stopped` — the signal stopped it; run the same name again to continue.
+ * - `halted` — the message itself was refused (`message-invalid`) or Telegram
+ *   was unreachable; nobody was charged with it. Fix the cause and run again.
+ * - `dry-run` — counted, not sent.
+ */
+export type TelegramBroadcastRunOutcome = 'finished' | 'stopped' | 'halted' | 'dry-run';
+export interface TelegramBroadcastReport {
+    readonly name: string;
+    readonly outcome: TelegramBroadcastRunOutcome | 'running';
+    readonly total: number;
+    readonly delivered: number;
+    /** The recipient blocked the bot, is gone, or never started it — do not address them again. */
+    readonly unreachable: number;
+    /** Refused for a reason about neither the recipient nor the message, or retries ran out. */
+    readonly failed: number;
+    /** A send that was in flight when a previous run died — not repeated. */
+    readonly uncertain: number;
+    readonly pending: number;
+    /** Why a `halted` run stopped. */
+    readonly halt?: TelegramSendFailure;
+}
+export declare function runTelegramBroadcast(config: TelegramBroadcastConfig): Promise<TelegramBroadcastReport>;
+/** What the standard sender delivers: a text, or a copy of a prepared message with its media. */
+export type TelegramBroadcastMessage = {
+    readonly text: string;
+    readonly parseMode?: 'HTML' | 'MarkdownV2';
+} | {
+    readonly copyFrom: {
+        readonly chatId: TelegramBroadcastRecipient;
+        readonly messageId: number;
+    };
+};
+export interface TelegramBroadcastSenderConfig {
+    readonly token: string;
+    readonly message: TelegramBroadcastMessage;
+    readonly apiRoot?: string;
+    readonly fetch?: typeof fetch;
+}
+/** The standard `send`: `sendMessage` or `copyMessage` through the Bot API, no bot library. */
+export declare function telegramBroadcastSender(config: TelegramBroadcastSenderConfig): TelegramBroadcastConfig['send'];
+//# sourceMappingURL=broadcast.d.ts.map

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

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

package/dist/telegram/local-files.d.ts

@@ -0,0 +1,63 @@
+/**
+ * A file the local Bot API server already wrote to disk.
+ *
+ * `telegram-bot-api` keeps what it downloads under `<dir>/<bot token>/`, and a
+ * bot sharing that directory reads the file straight from disk instead of
+ * downloading it again, then deletes it once handled. Two bots did this two
+ * ways: one refused anything leaving the bot's directory, the other joined
+ * `file_path` onto the root and read whatever that named. `file_path` comes
+ * from a server over the network; `../` in it, or a link inside the directory
+ * pointing out of it, turned the second into a read — and a delete — of any
+ * file the bot's user could reach.
+ *
+ * The containment is decided on real paths, after links are resolved, so a
+ * link inside the directory is judged by where it leads. A refusal is a
+ * reason, and its message never carries the path or the token: both are
+ * secrets in a journal, the token literally so.
+ */
+/**
+ * Why a file will not be handed out.
+ *
+ * - `root-not-absolute` — the configured root is relative, so it would mean
+ *   something different in every working directory.
+ * - `bot-directory-unavailable` — the root has no readable, writable directory
+ *   for this bot: the server is not sharing it, or the process may not delete.
+ * - `outside-bot-directory` — `file_path` leaves the bot's directory, by `../`,
+ *   by an absolute path elsewhere, or through a link.
+ * - `missing` — nothing is there (already handled, or never finished).
+ * - `not-a-file` — something is there, and it is not a regular file.
+ */
+export type TelegramLocalFileRefusal = 'root-not-absolute' | 'bot-directory-unavailable' | 'outside-bot-directory' | 'missing' | 'not-a-file';
+export declare class TelegramLocalFileError extends Error {
+    readonly reason: TelegramLocalFileRefusal;
+    constructor(reason: TelegramLocalFileRefusal);
+}
+export interface TelegramLocalFilesConfig {
+    /**
+     * The directory the Bot API server was started with (`--dir`), absolute, as
+     * this process sees it. The recommended variable is `BOT_API_FILES_ROOT`.
+     */
+    readonly root: string;
+    /** The bot's token: the server names the bot's directory after it. */
+    readonly token: string;
+}
+export type TelegramLocalFilesCheck = {
+    readonly ready: true;
+} | {
+    readonly ready: false;
+    readonly reason: TelegramLocalFileRefusal;
+};
+export interface TelegramLocalFiles {
+    /**
+     * The absolute path of `file_path` as `getFile` returned it — relative, or
+     * absolute inside the bot's directory as a `--local` server answers.
+     * Throws `TelegramLocalFileError`.
+     */
+    resolve(filePath: string): Promise<string>;
+    /** Delete a handled file, within the same boundary. Already gone is not an error. */
+    remove(filePath: string): Promise<void>;
+    /** Whether the bot's directory is there to read and delete from — for readiness. */
+    check(): Promise<TelegramLocalFilesCheck>;
+}
+export declare function createTelegramLocalFiles(config: TelegramLocalFilesConfig): TelegramLocalFiles;
+//# sourceMappingURL=local-files.d.ts.map

package/dist/telegram/local-files.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"local-files.d.ts","sourceRoot":"","sources":["../../src/telegram/local-files.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAMH;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,wBAAwB,GAChC,mBAAmB,GACnB,2BAA2B,GAC3B,uBAAuB,GACvB,SAAS,GACT,YAAY,CAAC;AAEjB,qBAAa,sBAAuB,SAAQ,KAAK;IAC/C,QAAQ,CAAC,MAAM,EAAE,wBAAwB,CAAC;IAE1C,YAAY,MAAM,EAAE,wBAAwB,EAI3C;CACF;AAED,MAAM,WAAW,wBAAwB;IACvC;;;OAGG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,sEAAsE;IACtE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,MAAM,uBAAuB,GAC/B;IAAE,QAAQ,CAAC,KAAK,EAAE,IAAI,CAAA;CAAE,GACxB;IAAE,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,wBAAwB,CAAA;CAAE,CAAC;AAEzE,MAAM,WAAW,kBAAkB;IACjC;;;;OAIG;IACH,OAAO,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAC3C,qFAAqF;IACrF,MAAM,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACxC,oFAAoF;IACpF,KAAK,IAAI,OAAO,CAAC,uBAAuB,CAAC,CAAC;CAC3C;AAYD,wBAAgB,wBAAwB,CACtC,MAAM,EAAE,wBAAwB,GAC/B,kBAAkB,CAoEpB"}

package/dist/telegram/operator-channel.d.ts

@@ -0,0 +1,72 @@
+/**
+ * The operator's Telegram chat: product events for people, not the journal.
+ *
+ * Two bots each carried a 250-line static logger posting new users, payments
+ * and errors into forum topics of one chat, and each mixed it with the process
+ * journal. They answer different readers. The journal is for the machine and
+ * the engineer and must never lose a line to a slow network; the chat is for a
+ * person and must never slow the bot down. So this is a separate thing, with
+ * the opposite guarantee: `post` returns at once and never throws, sending is
+ * paced below Telegram's per-chat limit, and when the chat cannot keep up the
+ * oldest message is dropped and counted rather than the bot waiting.
+ *
+ * What to post stays the application's. This owns the queue, the pacing, the
+ * topics, 429s and the bounded way down.
+ */
+import { type TelegramSendFailure } from './send-failure.js';
+export type TelegramChatId = number | string;
+export interface TelegramOperatorMessage {
+    readonly chatId: TelegramChatId;
+    /** The forum topic, when the chat has topics. */
+    readonly threadId?: number;
+    readonly text: string;
+}
+export interface TelegramOperatorDrop<TTopic extends string> {
+    readonly topic?: TTopic;
+    readonly text: string;
+    /**
+     * `overflow` — the queue was full and this was the oldest; `refused` —
+     * Telegram said no in a way repeating will not fix; `attempts` — it kept
+     * failing; `closed` — the channel closed before it was sent.
+     */
+    readonly reason: 'overflow' | 'refused' | 'attempts' | 'closed';
+    readonly failure?: TelegramSendFailure;
+}
+export interface TelegramOperatorChannelConfig<TTopic extends string> {
+    readonly chatId: TelegramChatId;
+    /** Topic name → forum `message_thread_id`. A topic not listed posts to the chat itself. */
+    readonly topics?: Readonly<Partial<Record<TTopic, number>>>;
+    /** Deliver one message — `telegramOperatorSender` or the application's own bot. */
+    readonly send: (message: TelegramOperatorMessage, signal: AbortSignal) => Promise<unknown>;
+    /** Default 200. The oldest message is dropped beyond it. */
+    readonly maxQueued?: number;
+    /** Pause between two sends. Default 3000 — Telegram allows about 20 per minute into a group. */
+    readonly minIntervalMs?: number;
+    /** Sends of one message before it is dropped. Default 3. */
+    readonly maxAttempts?: number;
+    /** Every message that will not arrive, with why. */
+    readonly onDropped?: (drop: TelegramOperatorDrop<TTopic>) => void;
+    /** Default: a timer. Rejects when `signal` aborts. */
+    readonly sleep?: (milliseconds: number, signal: AbortSignal) => Promise<void>;
+}
+export interface TelegramOperatorChannel<TTopic extends string> {
+    /** Queue one message. Returns at once and never throws. */
+    post(text: string, topic?: TTopic): void;
+    /** Messages waiting, the one in flight included. */
+    readonly pending: number;
+    /** Resolves once everything queued was sent or dropped, or when `signal` aborts. */
+    drain(signal?: AbortSignal): Promise<void>;
+    /** Stop: the message in flight is abandoned and the queue dropped as `closed`. */
+    close(): void;
+}
+export declare function createTelegramOperatorChannel<TTopic extends string = never>(config: TelegramOperatorChannelConfig<TTopic>): TelegramOperatorChannel<TTopic>;
+export interface TelegramOperatorSenderConfig {
+    readonly token: string;
+    readonly apiRoot?: string;
+    /** Default: plain text, so an operator message never fails on entity parsing. */
+    readonly parseMode?: 'HTML' | 'MarkdownV2';
+    readonly fetch?: typeof fetch;
+}
+/** The standard `send`: `sendMessage` through the Bot API, no bot library. */
+export declare function telegramOperatorSender(config: TelegramOperatorSenderConfig): TelegramOperatorChannelConfig<string>['send'];
+//# sourceMappingURL=operator-channel.d.ts.map

package/dist/telegram/operator-channel.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"operator-channel.d.ts","sourceRoot":"","sources":["../../src/telegram/operator-channel.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAGH,OAAO,EAA+B,KAAK,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AAEvF,MAAM,MAAM,cAAc,GAAG,MAAM,GAAG,MAAM,CAAC;AAK7C,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,MAAM,EAAE,cAAc,CAAC;IAChC,iDAAiD;IACjD,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,oBAAoB,CAAC,MAAM,SAAS,MAAM;IACzD,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB;;;;OAIG;IACH,QAAQ,CAAC,MAAM,EAAE,UAAU,GAAG,SAAS,GAAG,UAAU,GAAG,QAAQ,CAAC;IAChE,QAAQ,CAAC,OAAO,CAAC,EAAE,mBAAmB,CAAC;CACxC;AAED,MAAM,WAAW,6BAA6B,CAAC,MAAM,SAAS,MAAM;IAClE,QAAQ,CAAC,MAAM,EAAE,cAAc,CAAC;IAChC,2FAA2F;IAC3F,QAAQ,CAAC,MAAM,CAAC,EAAE,QAAQ,CAAC,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC;IAC5D,mFAAmF;IACnF,QAAQ,CAAC,IAAI,EAAE,CAAC,OAAO,EAAE,uBAAuB,EAAE,MAAM,EAAE,WAAW,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IAC3F,4DAA4D;IAC5D,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,gGAAgG;IAChG,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC,4DAA4D;IAC5D,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,oDAAoD;IACpD,QAAQ,CAAC,SAAS,CAAC,EAAE,CAAC,IAAI,EAAE,oBAAoB,CAAC,MAAM,CAAC,KAAK,IAAI,CAAC;IAClE,sDAAsD;IACtD,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC,YAAY,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CAC/E;AAED,MAAM,WAAW,uBAAuB,CAAC,MAAM,SAAS,MAAM;IAC5D,2DAA2D;IAC3D,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACzC,oDAAoD;IACpD,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,oFAAoF;IACpF,KAAK,CAAC,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC3C,kFAAkF;IAClF,KAAK,IAAI,IAAI,CAAC;CACf;AA4BD,wBAAgB,6BAA6B,CAAC,MAAM,SAAS,MAAM,GAAG,KAAK,EACzE,MAAM,EAAE,6BAA6B,CAAC,MAAM,CAAC,GAC5C,uBAAuB,CAAC,MAAM,CAAC,CA8IjC;AAED,MAAM,WAAW,4BAA4B;IAC3C,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,iFAAiF;IACjF,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,YAAY,CAAC;IAC3C,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,KAAK,CAAC;CAC/B;AAED,8EAA8E;AAC9E,wBAAgB,sBAAsB,CACpC,MAAM,EAAE,4BAA4B,GACnC,6BAA6B,CAAC,MAAM,CAAC,CAAC,MAAM,CAAC,CAgB/C"}

package/llms/application-grammy.txt

@@ -7,6 +7,7 @@ Contains: API reference: `stitchkit/application/grammy`  (docs/api/reference.md)
 
 Also read:
 - see `llms/application.txt` for the Managed application kernel guide
+- see `llms/telegram.txt` for the Telegram bots guide
 
 ==============================================================================
 # API reference: `stitchkit/application/grammy`  (docs/api/reference.md)
@@ -20,6 +21,10 @@ does not resolve grammY.
 | Export | Kind | Summary |
 |--------|------|---------|
 | `grammyPollingResource` | function | adapt an injected bot's long polling with distinct `onStart` readiness, observed completion and one stop chain |
+| `grammyBotResources` | function | a long-polling bot as `telegram-configuration` (optional `configure`, e.g. `setMyCommands`) then `telegram-polling`, both after the bot's `dependsOn`; updates admitted by batch and the end of polling reported to `onEnded` |
+| `GrammyBotResourcesConfig` / `GrammyBotResources` | _type_ | injected bot, `dependsOn`, `configure`, polling options, `onStart` / `onError` / `onEnded`; `{ configuration?, polling, resources }` in start order |
+| `TELEGRAM_CONFIGURATION_RESOURCE_ID` / `TELEGRAM_POLLING_RESOURCE_ID` | constant | the two stable ids a monitor, a test or a restart addresses |
+| `GrammyPollingEnd` | _type_ | `{ error? }` — how a poller that was ready ended on its own; never reported for a requested stop |
 | `createGrammyWebhookResource` | function | return a managed resource plus admission-guarded `handleUpdate`; HTTP hosting and webhook registration stay application-owned |
 | `GrammyWebhookUnavailableError` | class | stable `GRAMMY_WEBHOOK_NOT_ACCEPTING` rejection after webhook admission closes |
 | `GrammyPollingResourceConfig` | _type_ | injected bot, polling options, resource graph policy and isolated error observer |

package/llms/application.2.txt

@@ -319,6 +319,7 @@ cutovers are covered by the executable
 | `ApplicationConfig` / `ApplicationHandle` | _type_ | application declaration and its start/snapshot/subscription/admission/shutdown handle |
 | `ApplicationAdmission` / `ApplicationOperationLease` | _type_ | atomic process-local admission and idempotent release primitive |
 | `ManagedResource` / `ManagedResourceContext` / `ManagedResourceStartResult` | _type_ | resource lifecycle callbacks, shared deadlines, health reporting, separate readiness/completion promises and the value a resource publishes to its dependants |
+| `ManagedResourceAdmission` | _type_ | `context.admission`: `acquire()` now or `null`, and `acquireWhenAccepting(signal)` for a resource that fetches work — a poller waits instead of fetching while the application is starting or degraded; rejects on abort and once the application can no longer admit |
 | `ManagedResourceDependency` | _type_ | a dependency named by id or given as the resource itself — the second form is what `context.use(...)` can type |
 | `ManagedResourcePublished` | _type_ | the value type `context.use(resource)` returns, recovered from that resource's own `start` |
 | `ManagedResourcePublishesNoValue` | _type_ | what `context.use(...)` returns for a resource that publishes nothing — a branded refusal rather than `never`, so reading it does not silently compile |

package/llms/application.txt

@@ -755,40 +755,78 @@ Install grammY only in an application that imports the adapter:
 
 ```ts
 import { Bot } from 'grammy'
-import {
-  createGrammyWebhookResource,
-  grammyPollingResource,
-} from 'stitchkit/application/grammy'
+import { grammyBotResources } from 'stitchkit/application/grammy'
 ```
 
-For simple long polling, pass an already-configured bot:
+A long-polling bot is two resources, and one call gives both:
 
 ```ts
 const bot = new Bot(env.BOT_TOKEN)
 bot.command('start', (ctx) => ctx.reply('Hello'))
-bot.catch(({ error }) => internalLogger.error(error))
+bot.catch(({ error }) => logger.error('Telegram handler failed', { error }))
 
-const telegram = grammyPollingResource({
-  id: 'telegram',
+const telegram = grammyBotResources({
   bot,
-  required: true,
+  dependsOn: [database, http],             // what handlers need before the first update
+  configure: () => bot.api.setMyCommands([{ command: 'start', description: 'Start' }]),
+  onEnded: ({ error }) => stopProcess(error), // see below
 })
+
+const app = createApplication({ id: 'bot', resources: [database, http, ...telegram.resources] })
 ```
 
-Readiness follows grammY's `onStart`. Shutdown calls `bot.stop()` once and then
-awaits the retained `bot.start()` promise, because grammY documents that
-`stop()` alone does not wait for middleware completion.
+The ids are stable — `telegram-configuration`, then `telegram-polling` — so a
+monitor, a test or `app.restart()` can name them. `configure` runs on every
+start, before polling, so a command menu that failed to publish fails the start
+instead of hiding behind a bot that answers.
+
+**Updates are admitted by batch.** grammY confirms a batch to Telegram by
+asking for the next one, and it asks as soon as the batch went through
+middleware — whatever the middleware did. An update that arrived while the
+application was starting, degraded or stopping was refused by its handler and
+then confirmed as handled. The polling resource now waits for admission before
+asking for a batch, holds one admission lease for the batch it returns to
+grammY, and releases it when grammY asks for the next. On shutdown the batch in
+hand is finished before `bot.stop()` confirms the offset, so a stop neither
+loses an update nor hands the next process one this process already handled; a
+batch that arrives once the application will not admit it is never returned, and
+Telegram keeps it for the next process.
+
+**When polling ends on its own** — Telegram refused the token (401), another
+process took the bot (409), or `bot.catch` rethrew — grammY's poller does not
+recover in-process. The resource becomes `failed`, the application stops being
+ready, and `onEnded` is called once; it is never called for a stop the
+application asked for. The framework does not exit processes (ADR 0074): the
+entry point turns `onEnded` into its own shutdown and a non-zero exit so the
+supervisor starts a fresh process. The Telegram bot template shows the one way.
+
+**429s** are the application's for its own replies: install
+`@grammyjs/auto-retry` on `bot.api.config` with a bounded delay. Polling itself
+already waits Telegram's `retry_after`, and the broadcast and operator channel
+in `stitchkit/telegram` handle theirs.
+
+`grammyPollingResource` is the polling half on its own, for a bot that needs no
+configuration step; it admits updates the same way.
 
 For webhook ingress, `createGrammyWebhookResource` wraps provider-owned update
 handling with admission and drain. The application still mounts the HTTP route,
 verifies/configures its webhook and chooses the grammY framework adapter. An
 update accepted before shutdown may finish; a later update is rejected.
 
-The adapter never reads the token/env, installs commands, changes `bot.catch`,
+The adapter never reads the token or the environment, changes `bot.catch`,
 chooses retry plugins, drops pending updates, sends outbound messages or stores
 updates. A durable inbox/retry worker remains an application component, not a
 mode of this adapter.
 
+### A resource that fetches work
+
+`context.admission` is the application's admission as a resource sees it.
+`acquire()` answers now; `acquireWhenAccepting(signal)` waits until the
+application admits and then holds one operation — the right move for a poller or
+a queue consumer, which should not fetch at all while the application is not
+ready. It rejects with the signal's reason on abort, and with
+`ApplicationAdmissionError` once the application is shutting down or failed.
+
 ## What disappears from an application
 
 A typical small service can replace roughly 120–220 lines of generic signal,

package/llms/observability.txt

@@ -5,6 +5,9 @@
 
 Contains: Guide: Observability  (docs/guide/observability.md) · API reference: `stitchkit/observability`  (docs/api/reference.md)
 
+Also read:
+- see `llms/telegram.txt` for the Telegram bots guide
+
 ==============================================================================
 # Guide: Observability  (docs/guide/observability.md)
 ==============================================================================
@@ -831,6 +834,8 @@ audit event. See the [Observability guide](../guide/observability.md).
 | `DimensionCollision` / `SetRequestDimensionsOptions` | _type_ | explicit overwrite, preserve or error policy for dimension keys |
 | `createBoundedLogger` | function | decorate a `StitchLogger` with request context, shared sanitisation, redaction and total bounds |
 | `DEFAULT_REDACT_PATHS` | constant | baseline credential/token paths added to the sanitizer's sensitive-key policy |
+| `createJsonLogger` | function | the process journal: one JSON line per call in pino's shape (numeric `level`, epoch `time`, `msg`) on standard output, through `createBoundedLogger` — an `Error` in any field keeps name, message, stack and cause; secrets masked; `level` threshold, static `fields`, injectable `write` |
+| `JsonLoggerOptions` / `JsonLogLevel` / `JSON_LOG_LEVELS` | _type_ / constant | the bounded-logger options plus `level`, `fields`, `write`, `now`; pino's numbers `debug` 20 … `error` 50, which a line reader matches on |
 | `BoundedLoggerBounds` / `BoundedLoggerOptions` | _type_ | per-value and total record ceilings (`stringLengthByKey` raises the string bound for named keys such as `stack`) plus sink/redaction configuration |
 | `RequestEvent` | _type_ | the normalised audit event handed to the sink; opt-in HTTP cancellation rows carry `outcome: 'cancelled'` |
 | `runUnitOfWork` / `RunUnitOfWorkOptions` | function / _type_ | run work that did not arrive over a transport — an agent loop, a scheduled broadcast — inside one context, with the same completion record a request gets |

package/llms/server.4.txt

@@ -386,6 +386,9 @@ and our payload is wrong, which is the case a list of substrings quietly counts
 against the user. An unrecognised refusal leaves the recipient reachable: losing
 a working subscriber forever costs more than one wasted send.
 
+The rest of what a bot is assembled from — its resources, journal, operator
+channel, broadcasts and local Bot API files — is in [Telegram bots](telegram.md).
+
 ## Cookies
 
 ```ts