stitchkit 0.100.3 → 0.101.1

package/llms/stitchkit.txt

@@ -79,12 +79,12 @@ 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 45 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 46 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/react/keyboard` | browser | evolving | which part of a screen gets a key — ordered layers, one Escape per level, list zones with real focus; see [keyboard guide](keyboard.md) |
-| `stitchkit/agent-runtime` | server | evolving<br>_redefined in 22 of the 45 minors since 0.56.2, most recently 0.97.0_ | optional durable conversation/run loop, history, models, prompts, fencing and events |
+| `stitchkit/agent-runtime` | server | evolving<br>_redefined in 22 of the 46 minors since 0.56.2, most recently 0.97.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 |
@@ -94,7 +94,7 @@ 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 10 of the 45 minors since 0.56.2, most recently 0.100.0_ | managed resource graph, readiness, admission, schedules, subtree restart and bounded shutdown |
+| `stitchkit/application` | browser + server | evolving<br>_redefined in 10 of the 46 minors since 0.56.2, most recently 0.100.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 |

package/llms/telegram.txt

@@ -42,16 +42,21 @@ 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":{}`.
+error logged as `{ error }` does not become `"error":{}`, and its own fields —
+a `TelegramBotApiError`'s `error_code` and `parameters.retry_after` — are on the
+line beside them.
+
+A bot token is masked wherever it appears — a request URL in an error message,
+a local Bot API file path — with no configuration: `123456:[redacted]` keeps the
+bot's id, which is public and is what tells two bots apart in one journal. So is
+the password in an address and a query parameter named as a secret (`?token=`).
 
 ```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 })
@@ -67,11 +72,13 @@ query values inside any URL variable (`DATABASE_URL`), and each URL-encoded:
 import { createJsonLogger, secretValuesFromEnv } from 'stitchkit/observability'
 
 export const logger = createJsonLogger({
-  sensitiveUrlPatterns: [TELEGRAM_BOT_TOKEN_PATTERN],
   sensitiveValues: secretValuesFromEnv(process.env),
 })
 ```
 
+A string of your own — a message for a person, a report — masks bot tokens with
+`redactTelegramBotToken(text)` from `stitchkit/telegram`.
+
 A key added to the environment is masked from its first line; a URL's user name
 is left alone, since it names a role that appears in ordinary text.
 
@@ -128,7 +135,21 @@ const operators = createTelegramOperatorChannel<'errors'>({
 })
 ```
 
-Held-back messages reach `onDropped` as `repeated` or `over-budget`. What to post stays the bot's. On the way down, drain it within the grace period
+Held-back messages reach `onDropped` as `repeated` or `over-budget`.
+
+A bot that already sends its alerts itself — its own bot instance, its own retry
+— takes the window alone instead of switching the channel off with parameters:
+
+```ts
+import { createTelegramOperatorDedupe } from 'stitchkit/telegram'
+
+const admit = createTelegramOperatorDedupe<'errors'>({ windowMs: 10 * 60_000 })
+
+const verdict = admit(text, 'errors')
+if (verdict.send) await sendAlert(verdict.text) // the text carries the held-back counts
+```
+
+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.
 
@@ -249,6 +270,14 @@ itself be a secret — and says what to pass: set the takeover for one start and
 remove it. `checkTelegramWebhook` on a timer notices a webhook that moved
 elsewhere, which this process cannot see any other way.
 
+**Moving to it from a claim of your own.** A bot that tagged its webhook itself
+holds an address this one does not recognise, so the first claim is refused —
+`other-secret` when the address is the same, `owned-elsewhere` otherwise — and
+names its own host. Start once with `takeoverFrom` set to that host, then remove
+it. The tag is derived from the secret with a fixed context, so it is the same
+across stitchkit releases: that takeover is needed once per bot, not per
+upgrade. A secret rotation is a new owner, and takes a takeover too.
+
 **The update is recorded before Telegram is answered.** A handler that runs
 longer than Telegram waits — a large file from a local Bot API server — gets the
 same update again while it still works, and a process that answers and then
@@ -263,10 +292,55 @@ fix (a refused message, a blocked user) is abandoned; `maxAttempts` (5) ends
 the rest. Delivery is at least once: a handler that finished but could not be
 recorded as finished runs again.
 
+With grammY the handler is `bot.handleUpdate`, which wraps a middleware's error
+in a `BotError`; the intake unwraps it, so `retry`, `onFailure` and the error
+stored with the update are what the middleware threw — a `retry` that returns
+`false` for the bot's own terminal error sees that error.
+
 The store is an interface of six atomic steps (`TelegramUpdateStore`), so the
-bot's own database can hold it; `sqliteTelegramUpdateStore` takes a
-`bun:sqlite` or `node:sqlite` handle as it is, and `memoryTelegramUpdateStore`
-is for tests.
+bot's own database holds it:
+
+| Store | Takes |
+|---|---|
+| `sqliteTelegramUpdateStore` | a `bun:sqlite` `Database` or `node:sqlite` `DatabaseSync` as it is |
+| `postgresTelegramUpdateStore` | one `query(text, parameters)` over the client the bot already holds |
+| `memoryTelegramUpdateStore` | nothing — tests, or a bot that accepts losing unhandled updates to a restart |
+
+```ts
+import { postgresTelegramUpdateStore } from 'stitchkit/telegram'
+
+// Bun
+postgresTelegramUpdateStore({ query: (text, parameters) => sql.unsafe(text, [...parameters]) })
+// Prisma
+postgresTelegramUpdateStore({
+  query: (text, parameters) => prisma.$queryRawUnsafe(text, ...parameters),
+  createTable: false, // the migration below owns the table
+})
+// pg
+postgresTelegramUpdateStore({
+  query: (text, parameters) => pool.query(text, [...parameters]).then((result) => result.rows),
+})
+```
+
+Each rule is one conditional statement, so a claim is atomic across every
+process sharing the table. By default the table is created on first use; where
+migrations own the schema, `postgresTelegramUpdateStoreSchema(table)` is the
+statement to put in one.
+
+A store of your own — over an ORM, another database — is put through the same
+rules the shipped ones are, concurrent claims included:
+
+```ts
+import { checkTelegramUpdateStore } from 'stitchkit/telegram'
+
+test('our update store keeps the rules', async () => {
+  expect(await checkTelegramUpdateStore(() => ourStore(freshTable()))).toEqual([])
+})
+```
+
+A store that reads and then writes in two statements passes every test with one
+process and runs one update twice in production; the check races eight claims
+against each other to catch it.
 
 ## Files from a local Bot API server
 
@@ -313,23 +387,24 @@ injected grammY bot. → ADR 0143, ADR 0201 — [guide](../guide/telegram.md)
 | `verifyTelegramInitData` | function | verify a Mini App `initData` signature against the bot token in constant time, before reading anything out of it |
 | `VerifyTelegramInitDataOptions` | _type_ | raw `initData`, bot token, optional `maxAgeSeconds` bound and injected clock |
 | `TelegramInitDataVerification` | _type_ | `{ valid: true, data }` or a refusal carrying its reason |
-| `TelegramInitData` | _type_ | verified `user`/`receiver`, `authDate`, `ageSeconds`, `queryId`, `startParam`, `chatType`, `chatInstance` and every signed pair in `raw` |
-| `TelegramInitDataUser` | _type_ | camelCase user record inferred from Telegram's signed `user` payload |
+| `TelegramInitData` | _type_ | verified `user`/`receiver` as `TelegramUser`, `authDate`, `ageSeconds`, `queryId`, `startParam`, `chatType`, `chatInstance` and every signed pair in `raw` |
+| `parseTelegramUser` / `TelegramUser` | function / _type_ | Telegram's `snake_case` user — grammY's `ctx.from`, a Bot API `User`, a Mini App `user` — as the one camelCase record initData returns too; `undefined` when it is not a user |
 | `TelegramInitDataRefusal` | _type_ | `missing-hash` / `signature-mismatch` / `malformed` / `expired` — an expired string is not a forged one |
 | `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` |
+| `TelegramSendFailureReason` / `TELEGRAM_SEND_FAILURE_REASONS` | _type_ / constant | `blocked-by-user` / `user-deactivated` / `chat-not-found` / `not-started` / `rate-limited` / `message-invalid` / `server-error` / `unknown`, and the same as a list; a `Record<TelegramSendFailureReason, …>` over them fails to compile when a reason is added |
 | `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` and `sensitiveValues` (a bot token is always masked), `dedupe`; a drop is `overflow` / `refused` / `attempts` / `closed` / `repeated` / `over-budget` with its classification |
+| `createTelegramOperatorDedupe` / `TelegramOperatorDedupeVerdict` | function / _type_ | the channel's dedupe window alone, for a sender with its own bot and retry: `(text, topic?)` → `{ send: true, text }` with the held-back counts, or `{ send: false, reason: 'repeated' \| 'over-budget' }` |
 | `TelegramOperatorDedupe` | _type_ | `windowMs` (10 min): one message per `fingerprint` per window, the next one sent carries `repeatedLine(count)`; `maxPerWindow` (20) across fingerprints, the overflow counted onto the next one sent with `overBudgetLine(count)`; `now` |
 | `telegramOperatorSender` / `TelegramOperatorSenderConfig` | function / _type_ | the standard `send`: `sendMessage` into the chat and topic, plain text unless `parseMode`; with `'HTML'` the markup is cleaned and cut by what it shows, so the channel's cut never leaves a tag open |
 | `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` |
+| `TELEGRAM_BOT_TOKEN_PATTERN` / `redactTelegramBotToken` | constant / function | the secret half of a bot token — the bot's id before the colon is not matched; `redact` and every logger on it mask it already, `redactTelegramBotToken(text)` masks every token in a string to `123456:[redacted]` |
 | `claimTelegramWebhook` | function | set the webhook only where it already points here, or by naming the host it is taken from; confirm Telegram holds it; pending updates kept unless `dropPendingUpdates` |
 | `ClaimTelegramWebhookConfig` / `TelegramWebhookConfig` / `TelegramWebhookClaim` | _type_ | `token`, `url`, `secret`, `apiRoot`, `fetch`, `signal`; `takeoverFrom` (a host, or `'none'`), `allowedUpdates`, `maxConnections`, `dropPendingUpdates`; the claim's tagged `url`, `takenFrom`, `pendingUpdates` |
 | `TelegramWebhookClaimError` / `TelegramWebhookRefusal` / `TELEGRAM_WEBHOOK_NONE` | class / _type_ / constant | `owned-elsewhere` / `other-secret` / `not-confirmed` with `ownerHost` — a host, never a path; `'none'` names no webhook |
@@ -337,9 +412,12 @@ injected grammY bot. → ADR 0143, ADR 0201 — [guide](../guide/telegram.md)
 | `checkTelegramWebhook` / `TelegramWebhookState` | function / _type_ | whether the webhook still points here: `owned`, `ownerHost`, `pendingUpdates`, Telegram's `lastError` |
 | `receiveTelegramWebhook` / `ReceiveTelegramWebhookOptions` / `TelegramUpdateAcceptance` | function / _type_ | one webhook `Request`: 403 without the secret (compared in constant time), 405 for another method, 400 for no update, 200 once `accept` recorded it |
 | `createTelegramUpdateIntake` | function | webhook updates recorded before Telegram is answered and handled after: chat order kept, other chats alongside up to `maxConcurrent`, a renewed lease per attempt, a sweep that takes over what a restart or a dead process left, retries, `maxAttempts`, finished updates remembered `retainMs` to refuse repeats; at least once |
-| `TelegramUpdateIntakeConfig` / `TelegramUpdateIntake` / `TelegramUpdateEnvelope` / `TelegramUpdateFailure` / `TelegramUpdateStoreStep` | _type_ | `store`, `handle`, `retry`, `maxAttempts` (5), `leaseMs` (120 000), `pendingGraceMs` (60 000), `sweepEveryMs` (30 000), `retainMs` (24 h), `maxConcurrent` (32), `onFailure`, `onStoreError`, `now`; `accept(body)`, `start()`, `sweep()`, `idle()`, `close()` |
+| `TelegramUpdateIntakeConfig` / `TelegramUpdateIntake` / `TelegramUpdateEnvelope` / `TelegramUpdateFailure` / `TelegramUpdateStoreStep` | _type_ | `store`, `handle` (a grammY `BotError` is unwrapped: `retry`, `onFailure` and the stored error see what the middleware threw), `retry`, `maxAttempts` (5), `leaseMs` (120 000), `pendingGraceMs` (60 000), `sweepEveryMs` (30 000), `retainMs` (24 h), `maxConcurrent` (32), `onFailure`, `onStoreError`, `now`; `accept(body)`, `start()`, `sweep()`, `idle()`, `close()` |
 | `TelegramUpdateStore` / `StoredTelegramUpdate` / `TelegramUpdateState` / `TelegramUpdateSettlement` / `TelegramUpdateClaimOptions` / `TelegramUpdateDueQuery` | _type_ | the store an intake runs on: `add`, `claim`, `renew`, `settle`, `due`, `prune`, each atomic on one record — a claim takes `pending`, a due `failed` or a lapsed `processing`; renew and settle only by the attempt holding it |
 | `memoryTelegramUpdateStore` | function | the store in this process's memory — tests, or a bot that accepts losing unhandled updates to a restart |
 | `sqliteTelegramUpdateStore` / `SqliteTelegramUpdateStoreConfig` / `TelegramSqliteDatabase` | function / _type_ | the store in SQLite over the handle the application opened — `bun:sqlite` `Database` or `node:sqlite` `DatabaseSync`; `table` (default `telegram_updates`) created when missing |
+| `postgresTelegramUpdateStore` / `PostgresTelegramUpdateStoreConfig` / `TelegramPostgresQuery` | function / _type_ | the store in Postgres over the client the application holds, as one `query(text, parameters)` returning rows — Bun `sql.unsafe`, Prisma `$queryRawUnsafe`, `pg` `pool.query`; each rule one conditional statement; `table`, `createTable` (default `true`) |
+| `postgresTelegramUpdateStoreSchema` | function | the table and its index as a statement for a migration, safe to run twice |
+| `checkTelegramUpdateStore` | function | put any store through every rule, each on a fresh store from `make`, concurrent claims included; resolves with the violations, empty when it keeps them |
 
 ---

package/llms/{upgrading-0.74.0-0.100.0.txt → upgrading-0.74.0-0.101.0.txt}

@@ -1,14 +1,50 @@
-# Upgrading 0.74.0 → 0.100.0 — stitchkit docs slice
+# Upgrading 0.74.0 → 0.101.0 — stitchkit docs slice
 
 > Generated from the `docs/` tree by `bun run gen:llms`. The index of all slices is
 > `llms.txt` in this package.
 
-Contains: Guide: Upgrading, 0.74.0 → 0.100.0  (docs/guide/upgrading.md)
+Contains: Guide: Upgrading, 0.74.0 → 0.101.0  (docs/guide/upgrading.md)
 
 ==============================================================================
-# Guide: Upgrading, 0.74.0 → 0.100.0  (docs/guide/upgrading.md)
+# Guide: Upgrading, 0.74.0 → 0.101.0  (docs/guide/upgrading.md)
 ==============================================================================
 
+## Released migration: 0.101.0
+
+### `TelegramInitDataUser` is `TelegramUser`
+
+**Who must act:** code that names the type `TelegramInitDataUser` from
+`stitchkit/telegram`. The record is the same; its name now says it is any
+Telegram user, since `parseTelegramUser(ctx.from)` returns it for a Bot API user
+too.
+
+```ts
+// Before
+import type { TelegramInitDataUser } from 'stitchkit/telegram'
+function ensureAccount(user: TelegramInitDataUser) {}
+// After
+import type { TelegramUser } from 'stitchkit/telegram'
+function ensureAccount(user: TelegramUser) {}
+```
+
+### `TELEGRAM_BOT_TOKEN_PATTERN` matches the secret half only
+
+**Who must act:** code that uses `TELEGRAM_BOT_TOKEN_PATTERN` to find or cut a
+whole token. It now matches what follows `<bot id>:`, so a masking replace keeps
+the bot's id — `123456:[redacted]`. Masking needs nothing any more: `redact` and
+every logger on it mask bot tokens by shape; remove the pattern from
+`sensitiveUrlPatterns`, and use `redactTelegramBotToken(text)` for a string of
+your own.
+
+```ts
+// Before
+createJsonLogger({ sensitiveUrlPatterns: [TELEGRAM_BOT_TOKEN_PATTERN] })
+text.replace(new RegExp(TELEGRAM_BOT_TOKEN_PATTERN.source, 'g'), '[redacted]')
+// After
+createJsonLogger({})
+redactTelegramBotToken(text)
+```
+
 ## Released migration: 0.100.0
 
 ### watch capacity and session/live/delivery adoption

package/llms/upgrading.txt

@@ -11,7 +11,7 @@ Contains: Guide: Upgrading, general  (docs/guide/upgrading.md)
 
 Load this slice, then every range slice between your installed version and the target:
 
-- 0.74.0 → 0.100.0: `llms/upgrading-0.74.0-0.100.0.txt`
+- 0.74.0 → 0.101.0: `llms/upgrading-0.74.0-0.101.0.txt`
 - 0.61.0 → 0.73.0: `llms/upgrading-0.61.0-0.73.0.txt`
 - 0.44.0 → 0.60.0: `llms/upgrading-0.44.0-0.60.0.txt`
 - 0.37.0 → 0.37.0: `llms/upgrading-0.37.0.txt`