stitchkit 0.95.3 → 0.96.1

package/llms/upgrading.txt

@@ -11,9 +11,9 @@ Contains: Guide: Upgrading, general  (docs/guide/upgrading.md)
 
 Load this slice, then every range slice between your installed version and the target:
 
-- 0.69.0 → 0.95.0: `llms/upgrading-0.69.0-0.95.0.txt`
-- 0.55.0 → 0.68.0: `llms/upgrading-0.55.0-0.68.0.txt`
-- 0.37.0 → 0.53.0: `llms/upgrading-0.37.0-0.53.0.txt`
+- 0.70.0 → 0.96.0: `llms/upgrading-0.70.0-0.96.0.txt`
+- 0.57.0 → 0.69.0: `llms/upgrading-0.57.0-0.69.0.txt`
+- 0.37.0 → 0.56.0: `llms/upgrading-0.37.0-0.56.0.txt`
 
 # Upgrading stitchkit
 

package/llms-full.txt

@@ -60,7 +60,7 @@ own, recorded as an ADR.
 | `stitchkit/cli` | server | stable | `createCli` — the CLI transport, light (no MCP SDK / `ai`) |
 | `stitchkit/remote` | browser **and** server | stable | peer-free `implementRemote` for thin HTTP proxy processes |
 | `stitchkit/files` | server (Bun or Node) | stable | peer-free managed local-file boundary |
-| `stitchkit/telegram` | server (Bun or Node) | evolving | peer-free Telegram platform primitives — Mini App `initData` verification and Bot API send-failure classification |
+| `stitchkit/telegram` | server (Bun or Node) | evolving | peer-free Telegram platform primitives — Mini App `initData` verification, send-failure classification, resumable broadcasts, the operator channel and local Bot API files |
 | `stitchkit/tracking` | browser **and** server | evolving | visitor-tracking mechanics — `createTrackingClient`, the tab-shared outbox, the page-leave beacon, attribution, the contract factory; no event vocabulary, no React |
 | `stitchkit/tracking/server` | server (Bun or Node) | evolving | the decisions a tracking backend makes — dispositions, visit lease over an application-owned store, active intervals, presence; no database |
 | `stitchkit/release` | browser **and** server | evolving | a page follows the release it was built for — `createReleaseMarker` on the server, `createReleaseWatcher` in the browser, the `X-Build-Id` header and a socket event between them |
@@ -68,11 +68,11 @@ own, recorded as an ADR.
 | `stitchkit/geo` | server (Bun or Node) | evolving | managed GeoIP reader generations, last-known-good reload and the optional MaxMind adapter |
 | `stitchkit/oauth` | browser **and** server | evolving | provider-neutral Authorization Code + PKCE request and one-shot callback transaction mechanics |
 | `stitchkit/google` | server (Bun or Node) | evolving | optional Google code exchange and verified OIDC identity adapter |
-| `stitchkit/observability` | server | stable<br>_redefined in 2 of the 40 minors since 0.56.2, most recently 0.92.0_ | request/tool event projections — `createObservability`, trace context, sanitisation |
+| `stitchkit/observability` | server | stable<br>_redefined in 2 of the 41 minors since 0.56.2, most recently 0.92.0_ | request/tool event projections — `createObservability`, trace context, sanitisation |
 | `stitchkit/testing` | tests on Bun or Node | stable | in-process generated clients over a real Fetch handler, plus the managed-resource conformance kit |
 | `stitchkit/declaration` | browser + build and deployment tooling (Bun or Node) | evolving | `ProjectDeclarationSchema` — the one machine-readable statement a repository makes about itself |
 | `stitchkit/react` | browser + server rendering | stable | `createCursorQuery`, `createCacheBridge`, QueryClient and `ApiError` retry policy |
-| `stitchkit/agent-runtime` | server | evolving<br>_redefined in 21 of the 40 minors since 0.56.2, most recently 0.94.0_ | optional durable conversation/run loop, history, models, prompts, fencing and events |
+| `stitchkit/agent-runtime` | server | evolving<br>_redefined in 21 of the 41 minors since 0.56.2, most recently 0.94.0_ | optional durable conversation/run loop, history, models, prompts, fencing and events |
 | `stitchkit/agent-runtime/sandbox` | server | evolving | optional Linux Bubblewrap sessions, durable workspaces and a host HTTP credential gateway; see [sandbox guide](sandbox.md) |
 | `stitchkit/agent-runtime/testing` | tests on Bun or Node | evolving | credential-free replay, scripted provider faults, deterministic race controls and the agent-store conformance kit |
 | `stitchkit/agent-runtime/harness` | server | evolving | resource-aware process-local facade over the canonical Agent runtime; supervision stays outside |
@@ -82,8 +82,8 @@ own, recorded as an ADR.
 | `stitchkit/agent-runtime/sqlite/bun` | server (Bun) | evolving | durable built-in SQLite store for the agent runtime |
 | `stitchkit/agent-runtime/sqlite/node` | server (Node ≥ 22.5) | evolving | durable built-in SQLite store for the agent runtime |
 | `stitchkit-tui` | terminal (Bun) | evolving | optional official OpenTUI host over a caller-composed headless runtime |
-| `stitchkit/application` | browser + server | evolving<br>_redefined in 8 of the 40 minors since 0.56.2, most recently 0.95.0_ | managed resource graph, readiness, admission, schedules, subtree restart and bounded shutdown |
-| `stitchkit/application/grammy` | server | evolving | isolated grammY polling and webhook lifecycle adapters |
+| `stitchkit/application` | browser + server | evolving<br>_redefined in 9 of the 41 minors since 0.56.2, most recently 0.96.0_ | managed resource graph, readiness, admission, schedules, subtree restart and bounded shutdown |
+| `stitchkit/application/grammy` | server | evolving | a grammY bot as application resources — configuration, then polling with updates admitted by batch — and the webhook adapter |
 | `stitchkit/application/opentelemetry` | server | evolving | maps application snapshots onto an injected OpenTelemetry `Meter` |
 | `stitchkit/application/schemas` | browser + server | evolving | the application's snapshot, health and shutdown schemas alone, without the kernel |
 | `stitchkit/application/diagnostic-journal` | server | evolving | the local diagnostic journal — the one part of the kernel that spawns, locks and writes files |
@@ -7003,40 +7003,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,
-})
-```
-
-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.
+  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] })
+```
+
+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,
@@ -10463,6 +10501,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
@@ -12716,6 +12757,155 @@ One vocabulary for every side of the conversation — the server that runs the a
 page that shows the microphone — so a phase sent over the wire means the same on both ends.
 
 
+==============================================================================
+# Guide: Telegram bots  (docs/guide/telegram.md)
+==============================================================================
+
+# Telegram bots
+
+`stitchkit/telegram` holds what the Bot API itself asks of every bot, with no
+bot library; `stitchkit/application/grammy` makes a grammY bot a set of
+application resources. Together they are what a bot is assembled from, so that
+a bot's own code is its product and nothing else. A generated bot to start from:
+`bun create stitchkit my-bot --template telegram-bot`. Why it is shaped this
+way: [ADR 0201](../decisions/0201-a-telegram-bot-is-assembled-from-primitives.md).
+
+| Job | Where |
+|---|---|
+| the bot as resources: command menu, then long polling with updates admitted by batch | `grammyBotResources` — [application kernel](application-kernel.md#optional-grammy-adapter) |
+| the process journal | `createJsonLogger` from `stitchkit/observability` |
+| the operator's chat: product events, apart from the journal | `createTelegramOperatorChannel` |
+| a broadcast that survives crashes, deploys and Ctrl-C | `runTelegramBroadcast` |
+| a file the local Bot API server wrote to disk | `createTelegramLocalFiles` |
+| why a send was refused | `classifyTelegramSendFailure` — [auth and errors](auth-and-errors.md#telegram-mini-apps) |
+| Mini App `initData` | `verifyTelegramInitData` — [auth and errors](auth-and-errors.md#telegram-mini-apps) |
+| one Bot API call without a bot library | `callTelegramBotApi` |
+
+## The journal
+
+A bot's journal is `createJsonLogger`: one JSON object per line on standard
+output, in pino's shape — numeric `level` (`debug` 20, `info` 30, `warn` 40,
+`error` 50), `time` in epoch milliseconds, `msg` — so `pino-pretty` reads it on
+a terminal and a supervisor matching `"level":50` sees errors. Unlike pino, an
+`Error` under *any* key is written with its name, message, stack and cause; an
+error logged as `{ error }` does not become `"error":{}`.
+
+```ts
+import { createJsonLogger } from 'stitchkit/observability'
+import { TELEGRAM_BOT_TOKEN_PATTERN } from 'stitchkit/telegram'
+
+export const logger = createJsonLogger({
+  level: env.LOG_LEVEL,
+  fields: { service: 'my-bot' },
+  sensitiveUrlPatterns: [TELEGRAM_BOT_TOKEN_PATTERN],
+})
+
+logger.error('Application startup failed', { error })
+```
+
+The error line contract, for whatever recognises a failure from the journal: a
+line whose `level` is `50` or more is an error. There is no separate `fatal`;
+an unrecoverable end is an `error` line followed by a non-zero exit.
+
+## The operator channel
+
+The chat where people read about new users, payments and failures is not the
+journal. The journal must not lose a line to a slow network; the chat must not
+slow the bot down. `post` returns at once and never throws; sends are paced
+below Telegram's per-chat limit (one every 3 s by default), 429s wait the time
+Telegram named, and when the chat cannot keep up the oldest message is dropped
+and reported.
+
+```ts
+import { createTelegramOperatorChannel, telegramOperatorSender } from 'stitchkit/telegram'
+
+const operators = createTelegramOperatorChannel<'users' | 'payments' | 'errors'>({
+  chatId: env.OPERATOR_CHAT_ID,
+  topics: { users: 2, payments: 3, errors: 4 },   // forum message_thread_id
+  send: telegramOperatorSender({ token: env.BOT_TOKEN }),
+  onDropped: (drop) => logger.warn('Operator message dropped', { ...drop }),
+})
+
+operators.post(`New user ${user.id}`, 'users')
+```
+
+Every message is masked before it leaves: a bot token always — bots post their
+errors here, and an error about a local Bot API file carries the token in its
+path — plus any `sensitivePatterns` the bot adds; `telegramOperatorSender` also
+masks its own exact token. What to post stays the bot's. On the way down, drain it within the grace period
+and close it: `drain: (context) => operators.drain(context.signal)`,
+`close: () => operators.close()` in a resource.
+
+## Broadcasts
+
+A broadcast is a job with an end, so it is a function, not a resource:
+
+```ts
+import { runTelegramBroadcast, telegramBroadcastSender } from 'stitchkit/telegram'
+
+const report = await runTelegramBroadcast({
+  name: '2026-04-28-price-lock',
+  directory: env.STATE_DIRECTORY,            // a state root, never the release tree
+  recipients: () => audience.activeSubscribers(),
+  send: telegramBroadcastSender({
+    token: env.BOT_TOKEN,
+    message: { copyFrom: { chatId: env.DRAFTS_CHAT_ID, messageId: 42 } },
+  }),
+  signal: stop.signal,
+  onProgress: (progress) => logger.info('Broadcast', { ...progress }),
+})
+```
+
+- **Resumable by name.** The audience is written once on the first run; running
+  the same name again continues with that list. Progress is an append-only
+  journal beside it, one line before and one after each send.
+- **Nobody twice.** A send that was in flight when the process died is recorded
+  `uncertain` and not repeated. A signal stops between sends, after the one in
+  flight is recorded.
+- **Refusals by meaning.** A blocked, deactivated or never-started recipient is
+  `unreachable` and never addressed again. A 429 waits Telegram's
+  `retry_after` and sends the same recipient again; a server error is retried
+  with backoff up to `maxAttempts`, then `failed`. A message Telegram cannot
+  parse is not the recipient's fault: the run **halts** with them still pending,
+  so the run after the fix reaches them. So does Telegram being unreachable.
+- **Pacing** is `ratePerSecond`, 25 by default. `dryRun` counts and writes
+  nothing. One runner per name: a second concurrent run is refused.
+
+The same call works from a script (the process's signal) and inside a live
+application (the application's signal, with admission held by the caller).
+The recipient state contains Telegram ids: keep it in the state directory, out
+of git.
+
+## Files from a local Bot API server
+
+A local `telegram-bot-api` keeps downloaded files under `<dir>/<bot token>/`,
+and a bot sharing that directory reads them from disk and deletes them when
+done. `file_path` comes from a server over the network, so it is resolved only
+inside the bot's directory — `../`, an absolute path elsewhere and a link
+pointing out are refused, judged on real paths.
+
+```ts
+import { createTelegramLocalFiles } from 'stitchkit/telegram'
+
+const files = createTelegramLocalFiles({ root: env.BOT_API_FILES_ROOT, token: env.BOT_TOKEN })
+
+const { file_path } = await ctx.getFile()
+const path = await files.resolve(file_path)   // throws TelegramLocalFileError
+// … process it …
+await files.remove(file_path)
+```
+
+The recommended variable for the root is **`BOT_API_FILES_ROOT`** — the
+server's `--dir`, absolute, as the bot's process sees it. A relative `file_path`
+(a server without `--local`) and an absolute one inside the bot's directory (a
+server with `--local`) both resolve. A refusal carries a reason
+(`root-not-absolute`, `bot-directory-unavailable`, `outside-bot-directory`,
+`missing`, `not-a-file`) and never the path or the token. `files.check()`
+answers whether the directory is there to read and delete from; a resource that
+throws on `{ ready: false }` in `start` keeps the bot from answering before it
+can read its media.
+
+
 ==============================================================================
 # Guide: GeoIP  (docs/guide/geo.md)
 ==============================================================================
@@ -12812,6 +13002,43 @@ analytics policy belong to the application.
 
 # Upgrading stitchkit
 
+## Released migration: 0.96.0
+
+### resource-context-admission
+
+One breaking change in `stitchkit/application`: `ManagedResourceContext` gains a
+required `admission`. Every context the kernel hands a resource already carries
+it; only a context built by hand needs it.
+
+1. **Give a hand-built resource context an `admission`.** **Who must act:** a
+   project whose tests call a resource's phase directly with a context object
+   they wrote themselves (`resource.close?.({ applicationId, signal, … })`).
+   The type checker names each one:
+
+   ```ts
+   // before
+   await resource.close?.({ applicationId: 'test', signal, now, reportHealth, use })
+   // after
+   await resource.close?.({
+     applicationId: 'test',
+     signal,
+     now,
+     reportHealth,
+     use,
+     admission: { acquire: () => null, acquireWhenAccepting: () => new Promise(() => {}) },
+   })
+   ```
+
+   A test that needs real admission starts the resource inside
+   `createApplication` instead.
+
+2. **Nothing to do for grammY polling, but know what changed.** **Who must
+   act:** nobody. `grammyPollingResource` now admits updates by batch: it does
+   not fetch while the application is not accepting, and finishes the batch in
+   hand before `bot.stop()`. A project that wrote its own `getUpdates`
+   transformer for this (waiting on `app.admission` before returning a batch)
+   deletes it; keeping both waits twice and is harmless.
+
 ## Released migration: 0.95.0
 
 One breaking change in `stitchkit/application`: the process lifecycle ledger
@@ -17111,6 +17338,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 |
@@ -17288,6 +17516,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 |
@@ -17817,6 +18049,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 |
@@ -18289,9 +18523,10 @@ available from `stitchkit/contract`.
 
 ## `stitchkit/telegram`
 
-Peer-free server-only Telegram platform primitives. Importing this resolves no
+Peer-free server-only Telegram platform primitives — the Bot API's own
+protocols and the jobs every bot rewrote around them. Importing this resolves no
 bot library; `stitchkit/application/grammy` remains the lifecycle adapter for an
-injected grammY bot. → ADR 0143
+injected grammY bot. → ADR 0143, ADR 0201 — [guide](../guide/telegram.md)
 
 | Export | Kind | Summary |
 |--------|------|---------|
@@ -18304,6 +18539,16 @@ injected grammY bot. → ADR 0143
 | `classifyTelegramSendFailure` | function | name a refused Bot API send and separate "retry this send" from "stop addressing this recipient" |
 | `TelegramSendFailure` | _type_ | reason, `status`, Telegram-stated `retryAfterSeconds`, `retryable`, `recipientUnreachable` and which evidence produced the answer |
 | `TelegramSendFailureReason` | _type_ | `blocked-by-user` / `user-deactivated` / `chat-not-found` / `not-started` / `rate-limited` / `message-invalid` / `server-error` / `unknown` |
+| `runTelegramBroadcast` | function | a resumable broadcast by `name` under a state `directory`: audience written once, an append-only journal, pacing at `ratePerSecond` (25), 429 waits `retry_after`, unreachable recipients never addressed again, a `message-invalid` or unreachable Telegram halts without charging the recipient, a send in flight at a crash is `uncertain` and not repeated, `dryRun`, one runner per name |
+| `TelegramBroadcastConfig` / `TelegramBroadcastSend` / `TelegramBroadcastReport` / `TelegramBroadcastRunOutcome` / `TelegramBroadcastOutcome` / `TelegramBroadcastRecipient` | _type_ | `name`, `directory`, `recipients()`, `send({ recipient, attempt })`, `maxAttempts`, `signal`, `onProgress`; counts `delivered` / `unreachable` / `failed` / `uncertain` / `pending` and `finished` / `stopped` / `halted` / `dry-run` |
+| `telegramBroadcastSender` / `TelegramBroadcastSenderConfig` / `TelegramBroadcastMessage` | function / _type_ | the standard `send`: `sendMessage` with a text or `copyMessage` of a prepared message, through the Bot API |
+| `createTelegramOperatorChannel` | function | the operator chat, apart from the journal: `post(text, topic?)` returns at once and never throws; paced sends into forum topics, 429 honoured, oldest dropped on overflow, `drain(signal)` and `close()` for the way down |
+| `TelegramOperatorChannelConfig` / `TelegramOperatorChannel` / `TelegramOperatorMessage` / `TelegramOperatorDrop` / `TelegramChatId` | _type_ | `chatId`, `topics`, `send`, `maxQueued`, `minIntervalMs`, `maxAttempts`, `onDropped`, `sensitivePatterns` (a bot token is always masked); a drop is `overflow` / `refused` / `attempts` / `closed` with its classification |
+| `telegramOperatorSender` / `TelegramOperatorSenderConfig` | function / _type_ | the standard `send`: `sendMessage` into the chat and topic, plain text unless `parseMode` |
+| `createTelegramLocalFiles` | function | files the local Bot API server wrote under `<root>/<token>/`: `resolve(file_path)` and `remove(file_path)` only inside the bot's directory, judged on real paths so a link is judged by where it leads; `check()` for readiness. Recommended root variable: `BOT_API_FILES_ROOT` |
+| `TelegramLocalFilesConfig` / `TelegramLocalFiles` / `TelegramLocalFilesCheck` / `TelegramLocalFileError` / `TelegramLocalFileRefusal` | _type_ / class | `root`, `token`; refusals `root-not-absolute` / `bot-directory-unavailable` / `outside-bot-directory` / `missing` / `not-a-file`, never carrying the path or the token |
+| `callTelegramBotApi` / `TelegramBotApiCall` / `TelegramBotApiError` | function / _type_ / class | one Bot API method over `fetch`; a refusal keeps `error_code`, `description` and `parameters` for the classifier, and no error names the URL |
+| `TELEGRAM_BOT_TOKEN_PATTERN` | constant | the shape of a bot token, for a logger's `sensitiveUrlPatterns` |
 
 ---
 

package/llms.txt

@@ -9,7 +9,7 @@ Build with stitchkit: define a contract once, then `implement` it and serve it (
 Load the slice for each entrypoint your code imports — `import … from 'stitchkit/server'` → `llms/server.txt`; the root `stitchkit` import → `llms/stitchkit.txt`. A slice holds that entrypoint's API reference section and the guide pages whose home it is; every guide lives in exactly one slice, and a slice that needs another's guide names it under "Also read". Each file is at most 50.0 KB; a longer one continues in numbered parts, each naming the next at its top. Moving across versions: load `llms/upgrading.txt` and the range slices it lists between your version and the target. `llms-full.txt` inlines everything; it is far larger than a context window, so do not read it whole.
 
 ## Entrypoint slices
-- **stitchkit**: [llms/stitchkit.txt](llms/stitchkit.txt) 15.5 KB → [llms/stitchkit.2.txt](llms/stitchkit.2.txt) 35.0 KB → [llms/stitchkit.3.txt](llms/stitchkit.3.txt) 14.2 KB
+- **stitchkit**: [llms/stitchkit.txt](llms/stitchkit.txt) 15.6 KB → [llms/stitchkit.2.txt](llms/stitchkit.2.txt) 35.0 KB → [llms/stitchkit.3.txt](llms/stitchkit.3.txt) 14.2 KB
 - **stitchkit/live**: [llms/live.txt](llms/live.txt) 21.2 KB
 - **stitchkit/react**: [llms/react.txt](llms/react.txt) 8.6 KB
 - **stitchkit/tools**: [llms/tools.txt](llms/tools.txt) 44.9 KB → [llms/tools.2.txt](llms/tools.2.txt) 26.3 KB → [llms/tools.3.txt](llms/tools.3.txt) 25.4 KB
@@ -20,8 +20,8 @@ Load the slice for each entrypoint your code imports — `import … from 'stitc
 - **stitchkit/remote**: [llms/remote.txt](llms/remote.txt) 1.0 KB
 - **stitchkit/contract**: [llms/contract.txt](llms/contract.txt) 31.9 KB
 - **stitchkit/primitives**: [llms/primitives.txt](llms/primitives.txt) 9.3 KB
-- **stitchkit/server**: [llms/server.txt](llms/server.txt) 45.3 KB → [llms/server.2.txt](llms/server.2.txt) 14.6 KB → [llms/server.3.txt](llms/server.3.txt) 42.7 KB → [llms/server.4.txt](llms/server.4.txt) 37.3 KB → [llms/server.5.txt](llms/server.5.txt) 21.8 KB
-- **stitchkit/observability**: [llms/observability.txt](llms/observability.txt) 42.8 KB
+- **stitchkit/server**: [llms/server.txt](llms/server.txt) 45.3 KB → [llms/server.2.txt](llms/server.2.txt) 14.6 KB → [llms/server.3.txt](llms/server.3.txt) 42.7 KB → [llms/server.4.txt](llms/server.4.txt) 37.5 KB → [llms/server.5.txt](llms/server.5.txt) 21.8 KB
+- **stitchkit/observability**: [llms/observability.txt](llms/observability.txt) 43.4 KB
 - **stitchkit/agent-runtime**: [llms/agent-runtime.txt](llms/agent-runtime.txt) 46.6 KB → [llms/agent-runtime.2.txt](llms/agent-runtime.2.txt) 29.8 KB → [llms/agent-runtime.3.txt](llms/agent-runtime.3.txt) 31.8 KB
 - **stitchkit/agent-runtime/testing**: [llms/agent-runtime-testing.txt](llms/agent-runtime-testing.txt) 2.2 KB
 - **stitchkit/agent-runtime/harness**: [llms/agent-runtime-harness.txt](llms/agent-runtime-harness.txt) 4.1 KB
@@ -30,8 +30,8 @@ Load the slice for each entrypoint your code imports — `import … from 'stitc
 - **stitchkit/agent-runtime/openrouter**: [llms/agent-runtime-openrouter.txt](llms/agent-runtime-openrouter.txt) 1.1 KB
 - **stitchkit/agent-runtime/sqlite/bun**: [llms/agent-runtime-sqlite-bun.txt](llms/agent-runtime-sqlite-bun.txt) 1.8 KB
 - **stitchkit/agent-runtime/sqlite/node**: [llms/agent-runtime-sqlite-node.txt](llms/agent-runtime-sqlite-node.txt) 1.7 KB
-- **stitchkit/application**: [llms/application.txt](llms/application.txt) 42.1 KB → [llms/application.2.txt](llms/application.2.txt) 32.6 KB
-- **stitchkit/application/grammy**: [llms/application-grammy.txt](llms/application-grammy.txt) 1.5 KB
+- **stitchkit/application**: [llms/application.txt](llms/application.txt) 44.6 KB → [llms/application.2.txt](llms/application.2.txt) 32.9 KB
+- **stitchkit/application/grammy**: [llms/application-grammy.txt](llms/application-grammy.txt) 2.3 KB
 - **stitchkit/application/opentelemetry**: [llms/application-opentelemetry.txt](llms/application-opentelemetry.txt) 1.6 KB
 - **stitchkit/application/directory-inbox**: [llms/application-directory-inbox.txt](llms/application-directory-inbox.txt) 0.3 KB
 - **stitchkit/application/diagnostic-journal**: [llms/application-diagnostic-journal.txt](llms/application-diagnostic-journal.txt) 1.4 KB
@@ -39,7 +39,7 @@ Load the slice for each entrypoint your code imports — `import … from 'stitc
 - **stitchkit/testing**: [llms/testing.txt](llms/testing.txt) 30.8 KB
 - **stitchkit/agent-runtime/sandbox**: [llms/agent-runtime-sandbox.txt](llms/agent-runtime-sandbox.txt) 8.1 KB
 - **stitchkit/files**: [llms/files.txt](llms/files.txt) 2.9 KB
-- **stitchkit/telegram**: [llms/telegram.txt](llms/telegram.txt) 2.0 KB
+- **stitchkit/telegram**: [llms/telegram.txt](llms/telegram.txt) 12.0 KB
 - **stitchkit/tracking**: [llms/tracking.txt](llms/tracking.txt) 16.8 KB
 - **stitchkit/release**: [llms/release.txt](llms/release.txt) 8.9 KB
 - **stitchkit/tracking/server**: [llms/tracking-server.txt](llms/tracking-server.txt) 2.5 KB
@@ -52,9 +52,9 @@ Load the slice for each entrypoint your code imports — `import … from 'stitc
 
 ## Upgrading slices
 - **Upgrading — how to move across versions**: [llms/upgrading.txt](llms/upgrading.txt) 10.3 KB
-- **Upgrading 0.69.0 → 0.95.0**: [llms/upgrading-0.69.0-0.95.0.txt](llms/upgrading-0.69.0-0.95.0.txt) 46.6 KB
-- **Upgrading 0.55.0 → 0.68.0**: [llms/upgrading-0.55.0-0.68.0.txt](llms/upgrading-0.55.0-0.68.0.txt) 47.0 KB
-- **Upgrading 0.37.0 → 0.53.0**: [llms/upgrading-0.37.0-0.53.0.txt](llms/upgrading-0.37.0-0.53.0.txt) 32.6 KB
+- **Upgrading 0.70.0 → 0.96.0**: [llms/upgrading-0.70.0-0.96.0.txt](llms/upgrading-0.70.0-0.96.0.txt) 46.3 KB
+- **Upgrading 0.57.0 → 0.69.0**: [llms/upgrading-0.57.0-0.69.0.txt](llms/upgrading-0.57.0-0.69.0.txt) 44.4 KB
+- **Upgrading 0.37.0 → 0.56.0**: [llms/upgrading-0.37.0-0.56.0.txt](llms/upgrading-0.37.0-0.56.0.txt) 36.9 KB
 
 ## Guide (web)
 - [Getting started](https://github.com/max-listov/stitchkit/blob/master/docs/guide/getting-started.md): install, entrypoints, and a first contract → server → client app
@@ -80,6 +80,7 @@ Load the slice for each entrypoint your code imports — `import … from 'stitc
 - [Frontend integrations](https://github.com/max-listov/stitchkit/blob/master/docs/guide/frontend-integrations.md): React Router resource routes and a separate Vite development proxy
 - [React Query policy](https://github.com/max-listov/stitchkit/blob/master/docs/guide/react.md): request-local SSR clients, a browser singleton and ApiError retry rules
 - [Voice](https://github.com/max-listov/stitchkit/blob/master/docs/guide/voice.md): stitchkit/voice — sentences cut while a reply streams, the text a voice reads, a speech queue that synthesises ahead and stops on interruption
+- [Telegram bots](https://github.com/max-listov/stitchkit/blob/master/docs/guide/telegram.md): stitchkit/telegram — the journal, the operator channel, resumable broadcasts, local Bot API files; the bot as application resources
 - [GeoIP](https://github.com/max-listov/stitchkit/blob/master/docs/guide/geo.md): stitchkit/geo — a server-only managed reader, three observable states and last-known-good generation reloads
 - [Upgrading](https://github.com/max-listov/stitchkit/blob/master/docs/guide/upgrading.md): moving a project across stitchkit versions; how breaking changes are marked
 - [Project declaration](https://github.com/max-listov/stitchkit/blob/master/docs/guide/declaration.md): the optional machine-readable statement a repository makes about itself — identity, roles, build, requirements, release steps and the names of the values a deployment supplies

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "stitchkit",
-  "version": "0.95.3",
+  "version": "0.96.1",
   "description": "Contract-first backend framework — one defineContract() into an HTTP API, MCP tools, AI-agent tools and a typed client. Bun and Node.",
   "keywords": [
     "bun",