stitchkit 0.113.2 → 0.114.0

package/llms-full.txt

@@ -67,7 +67,7 @@ own, recorded as an ADR.
 | `stitchkit/process/owner-loss` | bundled server entry (Bun, POSIX) | evolving | narrow bootstrap that keeps the process runner lazy while carrying its owner-loss guard in a single-file bundle |
 | `stitchkit/files/packaging` | build time (Bun or Node) | evolving | installed native asset graph, integrity, Bun packaging plugin and the artifact loader check; no runtime install policy |
 | `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, send-failure classification, resumable broadcasts, the operator channel with dedupe, a Bot API transport that separates a request that never left from an unknown outcome, local Bot API files, webhook ownership and durable webhook update intake |
+| `stitchkit/telegram` | server (Bun or Node) | evolving | peer-free Telegram platform primitives — Mini App `initData` verification, send-failure classification, one outbound budget per bot token with weighted albums and shared 429 pauses, resumable broadcasts, the operator channel with dedupe, a Bot API transport that separates a request that never left from an unknown outcome, local Bot API files, webhook ownership and durable webhook update intake |
 | `stitchkit/telegram/html` | browser and server | evolving | Telegram's HTML as a tree — clean any markup to what Telegram accepts, cut long text into valid parts by what the reader sees, check markup before it is sent |
 | `stitchkit/telegram/screens` | server (Bun or Node) | evolving | a bot's menus as declared screens over grammY — typed paths, actions and input, message reconciliation, state in any `StorageAdapter`, a test chat |
 | `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 |
@@ -77,12 +77,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 58 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 59 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, the managed-resource conformance kit and manual time for schedules and retries |
 | `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 24 of the 58 minors since 0.56.2, most recently 0.113.0_ | optional durable conversation/run loop, history, models, prompts, fencing and events |
+| `stitchkit/agent-runtime` | server | evolving<br>_redefined in 24 of the 59 minors since 0.56.2, most recently 0.113.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 14 of the 58 minors since 0.56.2, most recently 0.110.0_ | managed resource graph, readiness, admission, schedules, subtree restart and bounded shutdown |
+| `stitchkit/application` | browser + server | evolving<br>_redefined in 14 of the 59 minors since 0.56.2, most recently 0.110.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 |
@@ -10012,9 +10012,11 @@ const doctor = defineCliCommand({
 it the canonical JSON output is unchanged. `exitCode` classifies a successfully
 validated result and must return an integer in `0..255`; failed `ToolResult`
 envelopes and the application-wide `exitCodes` mapping remain authoritative for
-failures. A throwing callback, invalid status or non-string presenter becomes a
-normalized `INTERNAL_SERVER_ERROR`, never partial success output. Void native
-commands cannot declare either callback.
+failures. A throwing or invalid exit-status callback becomes a normalized
+`INTERNAL_SERVER_ERROR`. A throwing or non-string `present` preserves the validated
+result on stdout and reports `CLI_PRESENTATION_FAILED` separately, as described
+under [Aggregate views](#aggregate-views). Void native commands cannot declare
+either callback.
 
 `--version`, a selected native command and its command help run before
 `resolveAuth`, services, context or runtime-tool factories. Top-level help is
@@ -10229,6 +10231,7 @@ newline-terminated JSON record on its respective stream; progress and CLI usage
 diagnostics remain ordinary stderr text. This keeps stdout pipeable and
 `2>/dev/null` clean. The process exit code carries the error class (`0` ok,
 `VALIDATION_ERROR → 1`, `UNAUTHORIZED → 2`, `FORBIDDEN → 3`, `NOT_FOUND → 4`,
+`CLI_PRESENTATION_FAILED → 8`,
 …) — override per app with `exitCodes`.
 
 ### A narrower question than "all of them"
@@ -10450,7 +10453,7 @@ would answer a question nobody asked.
 
 Three rules worth knowing before you rely on them:
 
-- **A field the result does not carry is an argument error.** A group of zero
+- **A field the result does not carry is a presentation error.** A group of zero
   over a misspelled field is indistinguishable from a true empty answer, and the
   caller reads it as data. The message names the fields that *are* there.
 - **An aggregate needs a collection** — the result itself when it is an array,
@@ -10464,6 +10467,17 @@ Three rules worth knowing before you rely on them:
 A failed call still reports its own error and exit code. An aggregate over an
 error is not an answer to the question that was asked.
 
+If the command succeeds but its requested view cannot be built, the CLI writes
+the complete original result to stdout, using the normal JSON format (`--json`
+still selects compact output). It writes a separate structured
+`CLI_PRESENTATION_FAILED` diagnostic to stderr and exits with `8`, configurable
+through `exitCodes`. Its `details.operationSucceeded: true` and `retryable: false`
+distinguish a presentation refusal from a failed operation; `details.cause`
+preserves the safe reason. Recover the answer from stdout instead of repeating
+the mutation. Domain retry hints are not appended to this diagnostic. CLI
+argument errors detected before execution still exit with `2`
+and have no successful result to preserve.
+
 ## Named profiles
 
 A CLI that talks to a deployed server needs an address and a credential per
@@ -12935,6 +12949,11 @@ 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.
 
+`bot-to-bot-disabled` is permanent but deliberately not `recipientUnreachable`:
+Telegram returns it when either bot has not enabled Bot to Bot messaging, so the
+missing setting may be the sender's. Do not retry it, and do not close the
+recipient's row on it.
+
 `TELEGRAM_SEND_FAILURE_REASONS` lists every reason. A table keyed by
 `TelegramSendFailureReason` — error codes, the text a person reads — fails to
 compile when a release adds one, instead of falling through to a default:
@@ -13097,7 +13116,7 @@ core never models them (ADR 0002). But stitchkit itself emits a set of its own:
 `FILE_INSPECTION_REJECTED`, `FILE_TOO_LARGE`, `FILE_EXISTS`,
 `REALTIME_CONTRACT_VIOLATION`, `APPLICATION_NOT_ACCEPTING`, `NOT_IMPLEMENTED`,
 `WAIT_TIMEOUT`,
-`WAIT_FAILED`, `CLI_COMMAND_UNAVAILABLE`, `DOWNLOAD_NOT_FOUND`, `VIEW_HTTP_ERROR`,
+`WAIT_FAILED`, `CLI_COMMAND_UNAVAILABLE`, `CLI_PRESENTATION_FAILED`, `DOWNLOAD_NOT_FOUND`, `VIEW_HTTP_ERROR`,
 `CONNECTION_TIMEOUT`, `CONNECTION_RESPONSE_TOO_LARGE`,
 `CONNECTION_REQUEST_FAILED`, `UPSTREAM_TOOL_ERROR`,
 `OPERATION_NOT_SUCCEEDED`, `STREAM_ITEM_INVALID`, `STREAM_FRAME_TOO_LARGE`,
@@ -15514,6 +15533,67 @@ 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.
 
+## One token, one outbound budget
+
+Telegram counts a bot's bulk messages per token, not per campaign, handler or
+module. `telegramOutboundBudget` is that budget once: every alias of one token
+in the process gets the same object, another token gets another, and every send
+through it spends its weight. → [ADR 0274](../decisions/0274-a-telegram-token-has-one-outbound-budget.md).
+
+```ts
+import { telegramOutboundBudget } from 'stitchkit/telegram'
+
+const budget = telegramOutboundBudget({
+  token: env.BOT_TOKEN,
+  messagesPerSecond: 24,
+})
+
+// The one transformer of the bot's client. No second limiter, no second
+// scheduler: campaigns, replies and every other send of this token share it.
+api.config.use((previous, method, payload, signal) =>
+  budget.run(method, payload, signal, () => previous(method, payload, signal)),
+)
+```
+
+- **The token is the identity, not the sender.** Two bot objects built from one
+  token share the budget; two different tokens do not. The registry keeps a
+  128-bit identity, never the credential, and `stats()` contains no token.
+- **A message is the unit.** `sendMediaGroup` and `sendPaidMedia` cost their
+  media length, `copyMessages` and `forwardMessages` cost their message ids, and
+  a follow-up call to action after an album costs one more. Reads and edits
+  (`getMe`, `getFile`, `editMessage*`, `deleteMessage`, `sendChatAction`) do not
+  spend the budget.
+- **The first send after idle is immediate; the rest are spaced.** This is a
+  strict budget, not a bucket that saves a burst: at 24/s the next send is due
+  one interval later. A 429 pauses the whole token; when it resumes, one send
+  is released at the deadline and the queue continues one interval at a time,
+  never as a stampede.
+- **It paces; it does not retry.** `run` calls the send once. A 429 pauses the
+  token for Telegram's `retry_after` (or `retryAfterFallbackMs` when Telegram
+  gave none) and rethrows; the caller's retry policy decides what happens next.
+  A 429 from an edit or a read is still a fact about the token and pauses later
+  sends too. A network failure is rethrown unchanged and stays `unknown`; a 5xx
+  is rethrown unchanged and stays `server-error`. Neither is retried by the
+  budget or pauses the token — repeating a send whose outcome is unknown is a
+  decision, not a primitive's silent guess.
+- **A wait can be cancelled.** `run`/`acquire` take an `AbortSignal`; a
+  cancelled waiter spends no slot and calls no provider. A granted send that is
+  then aborted is not evidence that Telegram did not accept it — keep the
+  outcome unknown rather than retrying it as a definite failure.
+- **Non-send retries wait without spending.** An edit or delete retry that got
+  a 429 first records the pause with `budget.pauseAfter(error)` (the `run` path
+  does this itself), then uses `await budget.waitUntilResumed(signal)`; it shares
+  the token's pause but does not take a message slot.
+
+`telegramBroadcastSender` and `telegramOperatorSender` still send through
+`callTelegramBotApi`; they are not a second budget. Their returned function does
+not expose the method and payload, so a product that uses one wraps the concrete
+`sendMessage`/`copyMessage` call in `budget.run` where it knows both, or passes
+its own sender. There is no generic wrapper around the opaque sender.
+`runTelegramBroadcast` keeps its per-run `ratePerSecond` and the operator
+channel keeps its per-chat `minIntervalMs`; those are caps of their own jobs,
+not another token quota. The token budget is the binding shared cap.
+
 ## The operator channel
 
 The chat where people read about new users, payments and failures is not the
@@ -16347,6 +16427,48 @@ analytics policy belong to the application.
 
 # Upgrading stitchkit
 
+## Released migration: 0.114.0
+
+**Who must act:** code with an exhaustive `switch` or `Record` over
+`TelegramSendFailureReason` or `TELEGRAM_SEND_FAILURE_REASONS`. Code that only
+reads `retryable` and `recipientUnreachable` needs no change.
+
+`classifyTelegramSendFailure` now returns `reason: 'bot-to-bot-disabled'` for a
+`400 USER_BOT_TO_BOT_DISABLED` ([ADR 0274](../decisions/0274-a-telegram-token-has-one-outbound-budget.md)).
+It is permanent for that send, so it is not retried; it is **not**
+`recipientUnreachable`, because Telegram disables bot-to-bot messaging when
+either bot has not enabled its Bot to Bot setting, and the missing setting may
+be the sender's.
+
+1. Add the reason to every exhaustive mapping:
+
+   ```ts
+   // before
+   const code: Record<TelegramSendFailureReason, string> = { /* … */ unknown: 'E_UNKNOWN' }
+   // after
+   const code: Record<TelegramSendFailureReason, string> = {
+     /* … */ 'bot-to-bot-disabled': 'E_BOT_TO_BOT', unknown: 'E_UNKNOWN',
+   }
+   ```
+
+   Search pattern: `TelegramSendFailureReason`, `TELEGRAM_SEND_FAILURE_REASONS`
+   and every `switch` over a send-failure reason.
+2. Type-check: the exhaustive table without the new member fails to compile.
+3. If the application wants one outbound budget per bot token, opt in at the
+   one transformer that already owns its Bot API calls:
+
+   ```ts
+   import { telegramOutboundBudget } from 'stitchkit/telegram'
+
+   const budget = telegramOutboundBudget({ token: env.BOT_TOKEN })
+   api.config.use((previous, method, payload, signal) =>
+     budget.run(method, payload, signal, () => previous(method, payload, signal)),
+   )
+   ```
+
+   Remove the old limiter rather than running it beside this one. See the
+   [Telegram guide](telegram.md#one-token-one-outbound-budget).
+
 ## Released migration: 0.113.0
 
 **Who must act:** custom `AgentRuntimeStoreDriver` adapters and custom `AgentRuntimeStore` implementations of `seedConversationInput`. The built-in memory and SQLite stores already implement the contract.
@@ -23272,7 +23394,7 @@ available from `stitchkit/contract`.
 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, ADR 0201 — [guide](../guide/telegram.md)
+injected grammY bot. → ADR 0143, ADR 0201, ADR 0274 — [guide](../guide/telegram.md)
 
 | Export | Kind | Summary |
 |--------|------|---------|
@@ -23287,7 +23409,8 @@ injected grammY bot. → ADR 0143, ADR 0201 — [guide](../guide/telegram.md)
 | `createTelegramBotTransport` / `TelegramBotTransportOptions` | function / _type_ | a `fetch` for the Bot API senders that connects before it writes, so a failure before the first byte is `TelegramNotDispatchedError`; connection attempt and budget, answer timeout and size, injectable resolver and socket factory — [guide](../guide/telegram.md#a-transport-that-knows-whether-a-request-left) |
 | `TelegramFetch` / `TelegramBotTransportOpen` / `TelegramBotTransportResolve` / `TelegramBotTransportSocket` | _types_ | the `(url, init) => Promise<Response>` the senders take; the transport's socket factory, resolver and the structural socket it needs (a Node `net.Socket` or `tls.TLSSocket` fits) |
 | `TelegramNotDispatchedError` / `TelegramNotDispatchedStage` | class / _type_ | a request that provably never left (`lookup`, `connect` or `request`), so repeating it cannot duplicate a message |
-| `TelegramSendFailureReason` / `TELEGRAM_SEND_FAILURE_REASONS` | _type_ / constant | `blocked-by-user` / `user-deactivated` / `chat-not-found` / `not-started` / `rate-limited` / `message-invalid` / `server-error` / `not-dispatched` / `unknown`, and the same as a list; a `Record<TelegramSendFailureReason, …>` over them fails to compile when a reason is added |
+| `TelegramSendFailureReason` / `TELEGRAM_SEND_FAILURE_REASONS` | _type_ / constant | `blocked-by-user` / `user-deactivated` / `chat-not-found` / `not-started` / `bot-to-bot-disabled` / `rate-limited` / `message-invalid` / `server-error` / `not-dispatched` / `unknown`, and the same as a list; a `Record<TelegramSendFailureReason, …>` over them fails to compile when a reason is added |
+| `telegramOutboundBudget` / `TelegramOutboundBudget` / `TelegramOutboundBudgetConfig` / `TelegramOutboundBudgetStats` | function / _type_ | one token-wide outbound budget: one object per token in the process, strict 24 messages/s by default, weighted albums and multi-message copies, `run(method, payload, signal, send)` as the transformer adapter, `pause`/`pauseAfter` for 429, `waitUntilResumed` for non-send retries and `stats`; it paces and never retries, and no public value carries the token |
 | `runTelegramBroadcast` | function | a resumable broadcast by `name` under a state `directory`: audience and journal durably recorded, pacing at `ratePerSecond` (25), exact retry delays within the finite declared budget, injected classifier, uncertain send outcomes never replayed, `dryRun`, one fenced 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` |
 | `TelegramBroadcastFailureSchema` / `TelegramBroadcastFailure` | schema / _type_ | injected `classify` answers retry-after/transient/permanent/ambiguous; exact provider delay is bounded by `maxRetryDelayMs` without shortening, unknown outcome remains uncertain and is never replayed |

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) 47.5 KB → [llms/stitchkit.2.txt](llms/stitchkit.2.txt) 38.1 KB
+- **stitchkit**: [llms/stitchkit.txt](llms/stitchkit.txt) 47.6 KB → [llms/stitchkit.2.txt](llms/stitchkit.2.txt) 38.1 KB
 - **stitchkit/live**: [llms/live.txt](llms/live.txt) 21.2 KB
 - **stitchkit/react**: [llms/react.txt](llms/react.txt) 8.6 KB
 - **stitchkit/react/keyboard**: [llms/react-keyboard.txt](llms/react-keyboard.txt) 9.2 KB
@@ -18,12 +18,12 @@ Load the slice for each entrypoint your code imports — `import … from 'stitc
 - **stitchkit/tools/contract**: [llms/tools-contract.txt](llms/tools-contract.txt) 0.2 KB
 - **stitchkit/tools/invoker**: [llms/tools-invoker.txt](llms/tools-invoker.txt) 0.2 KB
 - **stitchkit/tools/connections**: [llms/tools-connections.txt](llms/tools-connections.txt) 3.9 KB
-- **stitchkit/cli**: [llms/cli.txt](llms/cli.txt) 47.0 KB → [llms/cli.2.txt](llms/cli.2.txt) 22.5 KB
+- **stitchkit/cli**: [llms/cli.txt](llms/cli.txt) 33.9 KB → [llms/cli.2.txt](llms/cli.2.txt) 36.4 KB
 - **stitchkit/cli/publish**: [llms/cli-publish.txt](llms/cli-publish.txt) 1.5 KB
 - **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) 11.7 KB
-- **stitchkit/server**: [llms/server.txt](llms/server.txt) 44.2 KB → [llms/server.2.txt](llms/server.2.txt) 20.5 KB → [llms/server.3.txt](llms/server.3.txt) 45.6 KB → [llms/server.4.txt](llms/server.4.txt) 38.3 KB → [llms/server.5.txt](llms/server.5.txt) 22.9 KB
+- **stitchkit/server**: [llms/server.txt](llms/server.txt) 44.2 KB → [llms/server.2.txt](llms/server.2.txt) 20.5 KB → [llms/server.3.txt](llms/server.3.txt) 45.6 KB → [llms/server.4.txt](llms/server.4.txt) 38.6 KB → [llms/server.5.txt](llms/server.5.txt) 22.9 KB
 - **stitchkit/observability**: [llms/observability.txt](llms/observability.txt) 46.9 KB
 - **stitchkit/agent-runtime**: [llms/agent-runtime.txt](llms/agent-runtime.txt) 43.2 KB → [llms/agent-runtime.2.txt](llms/agent-runtime.2.txt) 45.9 KB → [llms/agent-runtime.3.txt](llms/agent-runtime.3.txt) 42.2 KB
 - **stitchkit/agent-runtime/testing**: [llms/agent-runtime-testing.txt](llms/agent-runtime-testing.txt) 2.6 KB
@@ -42,7 +42,7 @@ Load the slice for each entrypoint your code imports — `import … from 'stitc
 - **stitchkit/testing**: [llms/testing.txt](llms/testing.txt) 33.6 KB
 - **stitchkit/agent-runtime/sandbox**: [llms/agent-runtime-sandbox.txt](llms/agent-runtime-sandbox.txt) 8.3 KB
 - **stitchkit/files**: [llms/files.txt](llms/files.txt) 5.7 KB
-- **stitchkit/telegram**: [llms/telegram.txt](llms/telegram.txt) 36.6 KB
+- **stitchkit/telegram**: [llms/telegram.txt](llms/telegram.txt) 40.6 KB
 - **stitchkit/telegram/html**: [llms/telegram-html.txt](llms/telegram-html.txt) 2.7 KB
 - **stitchkit/telegram/screens**: [llms/telegram-screens.txt](llms/telegram-screens.txt) 21.2 KB
 - **stitchkit/tracking**: [llms/tracking.txt](llms/tracking.txt) 18.1 KB
@@ -64,11 +64,11 @@ 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) 12.7 KB
-- **Upgrading 0.103.13 → 0.113.0**: [llms/upgrading-0.103.13-0.113.0.txt](llms/upgrading-0.103.13-0.113.0.txt) 46.4 KB
-- **Upgrading 0.75.0 → 0.103.0**: [llms/upgrading-0.75.0-0.103.0.txt](llms/upgrading-0.75.0-0.103.0.txt) 46.3 KB
-- **Upgrading 0.61.0 → 0.74.0**: [llms/upgrading-0.61.0-0.74.0.txt](llms/upgrading-0.61.0-0.74.0.txt) 43.5 KB
-- **Upgrading 0.44.0 → 0.60.0**: [llms/upgrading-0.44.0-0.60.0.txt](llms/upgrading-0.44.0-0.60.0.txt) 43.9 KB
-- **Upgrading 0.37.0 → 0.37.0**: [llms/upgrading-0.37.0.txt](llms/upgrading-0.37.0.txt) 6.2 KB
+- **Upgrading 0.104.0 → 0.114.0**: [llms/upgrading-0.104.0-0.114.0.txt](llms/upgrading-0.104.0-0.114.0.txt) 43.6 KB
+- **Upgrading 0.79.0 → 0.103.13**: [llms/upgrading-0.79.0-0.103.13.txt](llms/upgrading-0.79.0-0.103.13.txt) 46.3 KB
+- **Upgrading 0.62.0 → 0.78.0**: [llms/upgrading-0.62.0-0.78.0.txt](llms/upgrading-0.62.0-0.78.0.txt) 42.2 KB
+- **Upgrading 0.44.0 → 0.61.0**: [llms/upgrading-0.44.0-0.61.0.txt](llms/upgrading-0.44.0-0.61.0.txt) 41.4 KB
+- **Upgrading 0.37.0 → 0.44.0**: [llms/upgrading-0.37.0-0.44.0.txt](llms/upgrading-0.37.0-0.44.0.txt) 14.7 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "stitchkit",
-  "version": "0.113.2",
+  "version": "0.114.0",
   "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",

package/llms/upgrading-0.37.0.txt

@@ -1,176 +0,0 @@
-# Upgrading 0.37.0 → 0.37.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.37.0 → 0.37.0  (docs/guide/upgrading.md)
-
-==============================================================================
-# Guide: Upgrading, 0.37.0 → 0.37.0  (docs/guide/upgrading.md)
-==============================================================================
-
-## The 0.37 migration
-
-Tool presentation is no longer an executable Zod parser. Replace the removed
-flatten helpers with the JSON Schema compiler, and choose the explicit
-`MountableTool` surface when using the advanced collection API:
-
-```ts
-// before
-const flat = flattenUnionsDeep(zodSchema)
-mountable.schema
-
-// after
-const flat = flattenToolJsonSchema(
-  z.toJSONSchema(zodSchema, { target: 'draft-07', io: 'input' }),
-)
-mountable.presentationSchema // model/MCP/manifest JSON Schema
-mountable.argumentSchema     // executable CLI argument adapter only
-```
-
-Contract and native handlers keep their original Zod schemas; MCP and agent SDK
-adapters now forward raw arguments so defaults, coercions, refinements and
-transforms execute exactly once inside Stitchkit. There are no compatibility
-exports for `flattenDiscriminatedUnion`, `flattenUnionsDeep` or
-`MountableTool.schema`. → ADR 0050
-
-Tool-call hooks now take one options object. Migrate all three callbacks; there
-are no positional overloads:
-
-```ts
-// before
-beforeToolCall: (toolName, args, context, endpoint) => {}
-afterToolCall: (toolName, args, result, durationMs, context, endpoint, error) => {}
-onToolError: (toolName, error, context, endpoint) => {}
-
-// after
-beforeToolCall: ({ toolName, args, context, endpoint }) => {}
-afterToolCall: ({ toolName, args, result, durationMs, context, endpoint, error }) => {}
-onToolError: ({ toolName, error, context, endpoint }) => {}
-```
-
-### MCP schema validation
-
-The standalone validator now takes one object and live MCP configs carry the
-same rules under `schemaValidation`. Migrate every positional call and every
-`onIncompatibleSchema` field; there is no old-shape overload:
-
-```ts
-// before
-validateMcpSchemas(services, 'throw', logger, { requireTypedProperties: true })
-createMcpHandler({ services, onIncompatibleSchema: 'throw' })
-
-// after
-validateMcpSchemas({ services, policy: 'throw', logger, requireTypedProperties: true })
-createMcpHandler({ services, schemaValidation: { policy: 'throw' } })
-```
-
-Put `extend` and `flattenUnionInput` beside `services`, not inside
-`schemaValidation`. The handler applies the profile to the exact prepared schema
-it advertises. Add `requirePortableFormats: true` when every custom JSON Schema
-format must be rejected before a client sees it.
-
-Native MCP registration also changed shape in 0.37. Move protected tools to the
-framework registrar; keep an SDK-raw tool only by naming the opt-out:
-
-```ts
-// before
-nativeTools: (server, auth) => server.registerTool(name, config, handler)
-
-// after — lifecycle, hooks and schema policy apply
-nativeTools: ({ registerTool }, auth) => registerTool({
-  name, description, identity, input, output, handler,
-})
-
-// after — intentionally raw
-nativeTools: ({ rawServer }, auth) => rawServer.registerTool(name, config, handler)
-```
-
-If a tool hook annotated `endpoint` as `MethodDef`, remove that annotation or
-use `OperationIdentity`: native operations have service/action/scope/method but
-no HTTP path.
-
-### Node-facing server types
-
-`stitchkit/server` remains Bun-concrete: an explicitly annotated `RawRoute`
-still receives `BunServer`. `stitchkit/node` no longer drags Bun declarations
-into a Node project. Its raw routes default the host server to `unknown`, and
-its Socket.IO handle exposes only Node capabilities:
-
-```ts
-// before — Node entry still leaked Bun-only fields and ambient types
-const route: RawRoute = { handler: (_req, ctx) => ctx.server?.upgrade(...) }
-const socket = await createSocketIOServer(config)
-socket.websocket
-
-// after — name a custom embedding host only when one exists
-const route: RawRoute<MyHostServer> = {
-  handler: (_req, ctx) => useHost(ctx.server),
-}
-const socket = await createSocketIOServer(config)
-socket.io
-socket.attach(nodeHttpServer)
-```
-
-Node consumers can remove `@types/bun` unless another dependency independently
-requires it.
-
-### Managed server shutdown
-
-`createServer()` and `serveNode()` now return the same structural managed
-lifecycle. Replace every direct runtime stop and parallel Socket.IO close:
-
-```ts
-// before — split ownership
-const socket = await createSocketIOServer(config)
-const server = createServer({
-  services,
-  websocket: socket.websocket,
-  rawRoutes: [socket.route],
-})
-server.stop()
-await socket.io.close()
-
-// after — one owner and one total deadline
-const socket = await createSocketIOServer(config)
-const server = createServer({ services, socket })
-const result = await server.shutdown({ gracePeriodMs: 30_000 })
-```
-
-On Node, keep the same `socket` field and replace `handle.close()` with
-`handle.shutdown()`. Runtime-specific diagnostics move under `handle.runtime`;
-do not use it as a second shutdown path. Standalone CLI/tools that create a
-Socket.IO handle without an HTTP server call `await socket.close()`.
-
-If Bun Socket.IO shares the port with a raw lane, keep the explicit composition
-but let the server mount the Socket.IO route:
-
-```ts
-createServer({
-  services,
-  socket,
-  websocket: composeWebSocketHandlers([
-    webSocketLane({ match: isRaw, handlers: rawHandlers }),
-    socketIoLane(socket.websocket),
-  ]),
-  rawRoutes: [rawUpgradeRoute],
-})
-```
-
-Move native Bun `routes` entries to `rawRoutes`. Native routes run before the
-Fetch handler and therefore cannot participate in admission or drain. Wire
-`SIGTERM`/`SIGINT` in the application; the first signal starts `shutdown()`, and
-a later signal may abort the same controller. Close MCP, databases and queues
-after the server result—those resources remain application-owned.
-
-Move a handshake policy from the Node-only callback shape inside
-`serverOptions` to the runtime-neutral top-level policy. It receives a Web
-`Request`, may be async, and returns whether to admit the handshake:
-
-```ts
-// before
-serverOptions: { allowRequest: (request, done) => done(null, allowed(request)) }
-
-// after
-allowRequest: (request) => allowed(request)
-```