stitchkit 0.115.0 → 0.117.0

package/llms-full.txt

@@ -52,7 +52,7 @@ own, recorded as an ADR.
 | `stitchkit/realtime` | browser, React Native/Hermes **and** server | evolving | typed realtime clients and retained topics with a required explicit Socket.IO peer loader |
 | `stitchkit/contract` | browser **and** server | stable | the contract layer alone — `defineContract`, errors, pagination |
 | `stitchkit/live` | browser **and** server | evolving | `defineEvents` — topic declarations beside the operation contract — and watched reads: `createWatchClient`, the value/difference frame and its reassembly |
-| `stitchkit/primitives` | browser **and** server | evolving | generic values and declarations for lifecycle, access, audit, delivery and exports |
+| `stitchkit/primitives` | browser **and** server | evolving | generic values and declarations for lifecycle, access, audit, delivery and exports, exact money and rounding tables |
 | `stitchkit/server` | server (Bun) | stable | `createServer`, `implement`, hooks, auth, Socket.IO server, server primitives |
 | `stitchkit/node` | server (Node ≥ 22) | stable | `serveNode` + the runtime-agnostic core — the Node mirror of `/server` |
 | `stitchkit/tools` | server | stable | `createMcpHandler`, `mountMcp`, `mountAgent`, the OAuth provider, native tools |
@@ -67,24 +67,27 @@ 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, 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/grammy` | server (Bun or Node) | evolving | the token's outbound budget as one grammY client transformer — a 429 that comes back as a response pauses the token, and a cancelled wait is a request that never left |
+| `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 per-chat 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/grammy` | server (Bun or Node) | evolving | the token's outbound budget as one grammY client transformer — a 429 that comes back as a response pauses its chat, and a cancelled wait is a request that never left |
 | `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 |
+| `stitchkit/tracking/contract` | browser **and** server | evolving | the wire shapes — the contract factory, event and visit schemas, the performance sample and its trust threshold; brings `zod` |
+| `stitchkit/tracking/performance` | browser **and** server | evolving | Web Vitals from real visitors, collected after load through the optional peer `web-vitals`; no `zod` |
 | `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 |
 | `stitchkit/voice` | browser **and** server | evolving | the mechanics of a live voice reply — `SentenceCutter`, `speakableText`, a `SpeechQueue` that synthesises ahead and stops on interruption, the conversation phases |
 | `stitchkit/geo` | server (Bun or Node) | evolving | managed GeoIP reader generations, last-known-good reload and the optional MaxMind adapter |
+| `stitchkit/xlsx` | browser **and** server | evolving | a workbook from rows and typed columns, with no dependency; text never runs as a formula |
 | `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 60 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 62 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/react/keyboard/testing` | server (Bun or Node) | evolving | the keyboard layers and zones without a DOM — fakes for the window, elements and key events beside the two engines, to test the order of layers, `scope`/`inert` and the edges of a zone in milliseconds |
-| `stitchkit/agent-runtime` | server | evolving<br>_redefined in 25 of the 60 minors since 0.56.2, most recently 0.115.0_ | optional durable conversation/run loop, history, models, prompts, fencing and events |
+| `stitchkit/agent-runtime` | server | evolving<br>_redefined in 25 of the 62 minors since 0.56.2, most recently 0.115.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 |
@@ -96,7 +99,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 60 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 62 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 |
@@ -448,7 +451,7 @@ Both entrypoints are **evolving**.
 ## Contract
 
 ```ts
-import { createTrackingContract } from 'stitchkit/tracking'
+import { createTrackingContract } from 'stitchkit/tracking/contract'
 
 export const tracking = createTrackingContract({
   scope: 'public',
@@ -647,6 +650,76 @@ has an identity. A bot gets a lease that no store holds, so its events are
 `createPresenceRegistry` is who is here now, in this process: touch it from
 `track`, read it for a live feed. It is honestly empty after a restart.
 
+## Real-visitor speed
+
+`stitchkit/tracking/performance` collects Web Vitals from the people who use the site. Install the
+optional peer `web-vitals` and call it once on the page:
+
+```ts
+import { createPerformanceCollector } from 'stitchkit/tracking/performance'
+
+createPerformanceCollector({
+  buildId: BUILD_ID,
+  url: '/api/tracking/performance',
+  visitId: () => client.visitId(),
+})
+```
+
+The library is fetched as its own chunk after `load`, when the browser is idle, so the measurement costs
+the page nothing it is measuring. Each load posts an `early` sample five seconds later and a `final` one
+as the page goes, both with `sendBeacon` and the same `id`: keep the later one. The body is a string, so
+the endpoint declares `safelistedBody: true`. A sample that could not leave waits in session storage for the
+next page, up to 20 of them, and of one load only the newest.
+
+A browser under automation sends nothing, and neither does an agent that admits to being Lighthouse,
+headless Chrome, GTmetrix or a crawler. Lighthouse with its default settings imitates an ordinary browser, so a
+local run with `webdriver` off cannot be told from a visitor.
+
+One load is one document: a client-side navigation stays under the route the page opened on, and whatever
+`web-vitals` reports after a back-forward restore is left out, because it would replace the load's numbers
+with a restore's. A second call on a page returns the running collector.
+
+A sample carries the route, the build, `mobile` or `desktop`, and the five metrics. **A metric that did not
+arrive is `null`, never zero**: most visits have no INP at all, and a zero would pull every average down.
+
+Parse a sample on your own endpoint and store it in your own table:
+
+```ts
+import { redactTrackingText } from 'stitchkit/tracking'
+import { PerformanceSampleSchema, summarizePerformanceMetric } from 'stitchkit/tracking/contract'
+
+const sample = PerformanceSampleSchema.parse(await request.json())
+await samples.upsert({ ...sample, route: redactTrackingText(sample.route) })
+
+const lcp = summarizePerformanceMetric(rows.map((row) => row.vitals.lcpMs))
+// { samples: 42, p75: 1840, p95: null } — a p95 needs 100 samples
+```
+
+The report is yours: which routes matter and what is slow are the application's words.
+
+## Privacy
+
+`redactTrackingText` masks passwords, sign-in credentials, API keys, bearer tokens and signed Telegram launch
+data in a URL or free text, and leaves paths and campaign parameters byte for byte. Text past 16 KiB is cut
+first, because the endpoint is open to anyone. `code` and `hash` count only beside the
+`state` or `auth_date` that makes them credentials, so a promo code stays. `redactTrackingValue` applies the
+same rule through a value of any shape. The client applies it to the landing path, the referrer and the
+campaign tags before sending or storing them. Apply it again on your ingest: anyone can post to that endpoint without running the client.
+
+## Is tracking losing events?
+
+`trackingTelemetryHealth(reports, baselines)` reads the outbox figures of a visit's bootstrap
+(`browserStreamId` as `stream`, `outboxState`, `outboxQueued`, `outboxDropped`) and answers `ok`, `degraded` or
+`unknown`. An application running without an outbox reports `unavailable` and reads as `degraded`. A browser repeats its lifetime `dropped` with
+every visit, so pass what each stream reported before the window as `baselines`, and only the growth counts.
+
+## Bundle weight
+
+`stitchkit/tracking` has no `zod` in its graph: `createTrackingClient` with `indexedDbOutboxStorage` is under
+8 KB gzip, a test holds that, and the build refuses a published file that reaches `zod`. The schemas live in
+`stitchkit/tracking/contract` for the server and a shared contract. Importing that in code a browser loads
+brings `zod` back, so keep a shared contract out of the storefront's client bundle.
+
 ## Not here
 
 GeoIP, event labels, funnels, reports, the analytics page, Socket.IO push into
@@ -5671,8 +5744,8 @@ stay pinned through authorization; `write_file` plans before it and opens the pa
 the parent it creates does not exist yet. Reads revalidate the pinned file identity;
 writes and patches revalidate the pinned parent identity; search and resource discovery descend
 only through opened directories. A path that changed during authorization refuses with `CONFLICT`.
-Policies compare path strings, so on a case-insensitive filesystem such as default macOS volumes a
-rule on `credentials` does not match `CREDENTIALS`; such a host must normalize in its own policy.
+A path spelled differently from the name stored on disk refuses before any policy reads it, so on a
+case-insensitive volume a rule on `credentials` cannot be passed by asking for `CREDENTIALS`.
 NUL bytes are refused before either host policy sees a path.
 Reads and edits open file candidates without blocking on special files, then require a regular
 file. A writerless FIFO therefore refuses instead of occupying a filesystem worker. `write_file`
@@ -5777,7 +5850,10 @@ remains the signal-only compatibility surface and additionally waits for admissi
 
 The in-memory store is a reference adapter and has process-local durability
 only. Production applications normally call `createAgentRuntimeStore()` and
-provide one database transaction driver:
+provide one database transaction driver. Its `transaction` owns the retry of a
+serialization conflict, wherever the database reports it: on a statement or on
+`COMMIT`, which some clients surface in a different shape. Pass
+`armCommitConflict` to `runAgentStoreConformance` to prove it:
 
 ```ts
 const store = createAgentRuntimeStore({
@@ -6366,6 +6442,46 @@ canonical run and failed assistant atomically, removes the run from recovery
 indexes, and publishes the resulting `run-state`. A run that moved since it was
 read returns a conflict; `staleOwner: true` is mandatory evidence, not a default.
 
+The same evidence holds inside one process when a store failure outlives the
+run's own handling. A store call around execution that throws is retried for
+about half a second, then decided by where the run stood. Retries bound a call
+that fails, not one that hangs, so give the store its own timeouts:
+
+| Failure | Outcome of `result` |
+|---|---|
+| reading or acquiring the run, retries spent, or a lost reply to the acquisition | resolves with reason `abandoned`, the cause on the operator's `run-terminal` |
+| the first assistant draft | resolves with reason `runtime_failure`, like a checkpoint later in the turn |
+| a conflict on a run another executor holds | rejects with the conflict; the record stays that executor's |
+| a conflict on a run still queued, behind another run | rejects with `AgentRunUnsettledError`; `recover()` or `resume` picks it up |
+| the terminal commit, or closing the run, retries spent | rejects with `AgentRunUnsettledError` |
+
+`AgentRunUnsettledError.run` is the record as last read, and the store may be ahead
+of it. Nothing in this process executes that run, and later turns of its
+conversation wait behind it. `recover()` skips a `running` run with a live owner, so
+a long-running process closes it itself once the store answers. Read the record
+first: with no owner or with `error.ownerId` it is this runtime's, and any other
+owner is executing it.
+
+```ts
+const settled = await ticket.result.catch(async (error) => {
+  if (!(error instanceof AgentRunUnsettledError)) throw error
+  const { conversationId, id: runId } = error.run
+  const current = await store.loadRun({ conversationId, runId })
+  if (current && [undefined, error.ownerId].includes(current.run.ownerId)) {
+    await runtime.abandon({
+      conversationId,
+      runId,
+      expectedRevision: current.run.revision,
+      staleOwner: true,
+    })
+  }
+  throw error
+})
+```
+
+A `queued` run lost to a run ahead of it, and `runtime.resume()` can run it instead
+once that one ends.
+
 ## Store operations
 
 `AgentRuntimeStore` remains the runtime-facing aggregate. Application adapters
@@ -9349,6 +9465,23 @@ migration.
 literal in the type; division and rational shares return an explicit remainder. It does not own
 exchange rates.
 
+`moneyFromDecimal('RUB', '5041.82', 2)` and `moneyToDecimal(value, 2)` cross between major units and
+minor ones with the currency's scale as a parameter, and a value finer than that scale is refused
+rather than cut. `multiplyMoneyByDecimal(price, '2.5', policy)` computes the exact product and rounds it
+once. `roundMoney(value, policy)` brings an amount to a table's steps:
+
+```ts
+const shelfPrice = defineRoundingPolicy({
+  mode: 'half-up', // or 'half-even', 'up', 'down'
+  tiers: [{ below: '100000', step: '100' }, { step: '1000' }], // minor units
+})
+roundMoney(moneyFromDecimal('RUB', '5041.82', 2), shelfPrice) // { minor: '504000', currency: 'RUB' }
+```
+
+A policy is data, so it can be stored with the prices it produced. `roundDecimal(value, policy)` is
+the same table over a plain decimal. `DecimalStringSchema` accepts one canonical spelling and refuses a
+JSON number; `DecimalInputSchema` takes a spelling such as a database's `10.50` to the canonical one.
+
 `defineUnitSystem` stores exact canonical decimal strings. Every conversion is an application
 rational with an id. A converted `QuantityProjection` is `derived` and carries both its source and
 conversion id; a form/database value can be marked `recorded`. Whether a derived projection is
@@ -10483,7 +10616,9 @@ myapp item_list --sort messages --top 5 --json                # the same five, a
 myapp item_list --sort name --ascending                       # ordered the other way
 ```
 
-Groups come back largest first for the same reason. A record that carries no
+Groups come back largest first for the same reason, in the printed bytes even when a key looks
+like a number; a reader that parses them into a JavaScript object reorders such keys itself.
+A string equal to `null` or `(absent)` is quoted, so it stays apart from the missing value. A record that carries no
 value for the sort field sorts **last in both directions**: it is not the
 smallest, it is not on the scale at all, and letting it lead an ascending list
 would answer a question nobody asked.
@@ -15916,19 +16051,46 @@ cast, and a send cancelled in the queue then waits for its slot and fails as
   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.
+- **Two lanes share one rate.** A call is `interactive` by default; a campaign passes
+  `{ lane: 'bulk' }` to `run` or `acquire`, or installs
+  `telegramBudgetTransformer(budget, { lane: 'bulk' })` on its own `Api`. A waiting
+  interactive call is granted first, so a reply never queues behind recipients;
+  the wait it can still see is the interval of the grant before it, up to one
+  album. Bulk runs at whatever rate replies leave, and the sum never exceeds
+  `messagesPerSecond`.
 - **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.
+  one interval later. When a pause ends, one send is released at the deadline and
+  the queue continues one interval at a time, never as a stampede.
+- **A 429 holds the chat that got it.** Telegram words a group's limit, a chat's
+  pace and the bot's own limit alike, and only the addressee differs, so `run`
+  pauses the `chat_id` of the refused send and every other chat of the token goes
+  on at the shared rate. A person's reply does not wait behind a notification
+  group on its limit, and neither does a campaign. Refusals from
+  `tokenPauseChats` different chats (default 3) inside `tokenPauseWindowMs`
+  (default 5000) are read as the bot's own limit and pause the whole token, and so
+  does a 429 with no chat in the payload. `stats().pausedChats` counts the chats
+  on a pause; `stats().pausedForMs` is the token's.
+- **A chat known to hit its limit can keep a 429 to itself.** A notification group
+  runs into its per-minute limit as a matter of course. `{ refusal: 'call' }` on `run`,
+  or `telegramBudgetTransformer(budget, { refusal: 'call' })` on that group's own `Api`,
+  makes the refusal concern that send alone: nothing pauses and nothing counts towards
+  `tokenPauseChats`. The call still spends the budget and waits out other pauses, and
+  what to do with the refused message stays the caller's decision.
+- **A wait can be bounded.** A burst to one chat on pause otherwise queues without
+  limit. `{ maxWaitMs }` on `run` or `acquire`, or on
+  `telegramBudgetTransformer(budget, { maxWaitMs })`, ends a call that waited that
+  long with `TelegramNotDispatchedError`, stage `queue`: nothing was sent and no
+  message was spent, so repeating it is safe.
+- **It paces; it does not retry.** `run` calls the send once. A 429 pauses for
+  Telegram's `retry_after` (or `retryAfterFallbackMs` when Telegram gave none) and
+  rethrows; the caller's retry policy decides what happens next.
   The refusal may be thrown or returned: a client transformer sits below the
   place where grammY turns Telegram's `{ ok: false, error_code: 429, … }` body into
   a `GrammyError`, so `run` reads that body too and hands it back unchanged.
-  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
+  A 429 from an edit or a read concerns that call and pauses nothing;
+  `budget.pauseAfter(error, { chatId })` remains for a caller who decides otherwise, and pauses
+  the token when it names no chat. 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.
@@ -15940,9 +16102,9 @@ cast, and a send cancelled in the queue then waits for its slot and fails as
   the client's own error — not evidence that Telegram did not accept it — so
   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.
+  a 429 records the pause with `budget.pauseAfter(error, { chatId })`, then uses
+  `await budget.waitUntilResumed(signal, { chatId })`; it shares that chat's pause
+  and the token's, and takes no message slot. Without `chatId` it pauses the token.
 
 `telegramBroadcastSender` and `telegramOperatorSender` still send through
 `callTelegramBotApi`; they are not a second budget. Their returned function does
@@ -16780,12 +16942,171 @@ Download schedules, licenses, database paths, attribution persistence and
 analytics policy belong to the application.
 
 
+==============================================================================
+# Guide: XLSX  (docs/guide/xlsx.md)
+==============================================================================
+
+# XLSX
+
+`stitchkit/xlsx` turns rows into a workbook. It is evolving, it needs nothing beyond the `zod` the package
+already requires, and it runs wherever
+`CompressionStream` does: Bun, Node and a browser.
+
+```ts
+import { defineMoney } from 'stitchkit/primitives'
+import { renderXlsx, XLSX_MEDIA_TYPE } from 'stitchkit/xlsx'
+
+const rub = defineMoney('RUB')
+
+const bytes = await renderXlsx({
+  sheets: [
+    {
+      name: 'Orders',
+      columns: [
+        { key: 'title', header: 'Title', type: 'text' },
+        { key: 'count', header: 'Count', type: 'number', format: '0.00' },
+        { key: 'day', header: 'Day', type: 'date' },
+        { key: 'at', header: 'Created', type: 'datetime', timeZone: 'Asia/Bangkok' },
+        { key: 'total', header: 'Total', type: 'money', currency: 'RUB', scale: 2 },
+        { key: 'paid', header: 'Paid', type: 'boolean' },
+      ],
+      rows: [
+        {
+          title: 'First order',
+          count: '2.5',
+          day: '2026-11-03',
+          at: new Date(),
+          total: rub.create('504182'),
+          paid: true,
+        },
+      ],
+    },
+  ],
+})
+
+return new Response(bytes, {
+  headers: {
+    'content-type': XLSX_MEDIA_TYPE,
+    'content-disposition': `attachment; filename*=UTF-8''${encodeURIComponent('Übersicht.xlsx')}`,
+  },
+})
+```
+
+A missing or `null` value leaves the cell empty. The first row holds the headers, stays frozen and carries a
+filter. The same input produces the same bytes on one runtime; Bun and Node compress differently.
+
+## Column types
+
+| `type` | Cell value | In the file |
+|---|---|---|
+| `text` | string | text, whatever it looks like: `007` keeps its zeros |
+| `number` | number, bigint or decimal string | a number, with an optional Excel `format` |
+| `date` | `YYYY-MM-DD` | a date serial; a calendar date has no time zone to get wrong |
+| `datetime` | `Date` or ISO instant with an offset | the wall clock of the column's `timeZone` to the second, since a cell stores no zone |
+| `money` | `Money` in the column's `currency` | a number with `scale` places and the currency in its format |
+| `boolean` | boolean | a boolean |
+
+## What it refuses
+
+A value of the wrong type throws `XlsxCellError` naming the cell, such as `sheet "Orders" B2: expected a
+number or a decimal string`, instead of landing as a wrong cell.
+
+Excel keeps numbers as doubles, so 15 significant digits are what survives. A decimal string or `Money` with
+more refuses rather than turning into a different amount. Keep such a value in a `text` column if it must
+stay exact and needs no arithmetic. Dates before 1900-03-01 refuse too: Excel counts a leap day that never
+happened, so its serials before it are off by one.
+
+A wall clock cannot tell the two hours of a daylight-saving change apart: 05:30Z and 06:30Z on a New York
+autumn night are the same cell. Use `UTC` for a column whose order must survive that hour.
+
+## Text is never a formula
+
+Cells are written as inline strings, so `=HYPERLINK("x")` from a user's input is text a reader shows,
+and the file has no formula element at all. A cell that starts with `=`, `+`, `-` or `@` also carries Excel's
+quote prefix, so it stays text when a person edits that cell.
+
+## Limits
+
+Everything is built in memory, up to Excel's own 1 048 576 rows per sheet. There is no reading, no
+charts, no merged cells and no streaming: an application that needs them takes a library.
+
+
 ==============================================================================
 # Guide: Upgrading  (docs/guide/upgrading.md)
 ==============================================================================
 
 # Upgrading stitchkit
 
+## Released migration: 0.117.0
+
+### telegram-chat-pause
+
+**Who must act:** code that relied on a 429 to one chat to stop the token's other chats. A bot that
+only sends needs no change: its other chats stop waiting.
+
+`run` pauses the `chat_id` of a refused send; the token pauses when `tokenPauseChats` chats are refused
+inside `tokenPauseWindowMs`, or when the call has no chat
+([ADR 0278](../decisions/0278-a-telegram-429-holds-the-chat-that-got-it.md)). A second budget kept under a
+derived key to isolate one group is no longer needed: remove it. Where one refusal must still stop everything,
+say so:
+
+```ts
+// before
+await api.sendMessage(chatId, text)
+// after
+await api.sendMessage(chatId, text).catch((error) => {
+  budget.pauseAfter(error)
+  throw error
+})
+```
+
+The catch belongs at the `Api` call, where grammY has turned a returned refusal into a thrown one. A raw
+`budget.run` around a client transformer's `send` gets that refusal as a value.
+
+Search pattern: `budget.run`, and budgets created under a key derived from the token.
+
+### tracking-contract-entry
+
+**Who must act:** code that imports `createTrackingContract` or a tracking schema or wire type from
+`stitchkit/tracking`. Code that only uses the browser client needs no change.
+
+The wire shapes moved to `stitchkit/tracking/contract`, so a page that sends events no longer carries `zod`
+([ADR 0280](../decisions/0280-real-visitor-speed-is-collected-after-the-page.md)):
+
+```ts
+// before
+import { createTrackingContract, createTrackingSchemas } from 'stitchkit/tracking'
+// after
+import { createTrackingContract, createTrackingSchemas } from 'stitchkit/tracking/contract'
+```
+
+Search pattern: imports from `stitchkit/tracking` naming `createTrackingContract`, `createTrackingSchemas`,
+`UtmData`, `AttributionData`, `TrackingEventEnvelope`, `TrackingDisposition`, `TrackEvents*`, `VisitEntryContext`,
+`VisitBootstrapResponse`, `TrackingOutboxState` or `DEFAULT_BUILD_ID_PATTERN`.
+
+## Released migration: 0.116.0
+
+### send-only-telegram-pause
+
+**Who must act:** code that relied on a 429 from `editMessage*`, `deleteMessage` or a read to stop a
+token's sends. Code that only sends needs no change.
+
+`run` pauses the token only on a method that spends the budget
+([ADR 0277](../decisions/0277-a-telegram-budget-serves-replies-first.md)). Where an edit must still stop
+the sends, say so:
+
+```ts
+// before
+await budget.run('editMessageText', payload, signal, send)
+// after
+await budget.run('editMessageText', payload, signal, send).catch((error) => {
+  budget.pauseAfter(error)
+  throw error
+})
+```
+
+Search pattern: `budget.run` next to edit and read methods.
+
 ## Released migration: 0.115.0
 
 ### contained-cli-downloads
@@ -22135,6 +22456,10 @@ schedules, transports and file generation remain application-owned.
 | `PermissionGrantMatrix` / `PermissionCheckResult` | _types_ | compile-time complete matrix and unknown/allowed/denied runtime result |
 | `defineMoney` / `createMoneySchema` | functions | fixed-currency JSON-safe minor-unit value and Zod schema |
 | `addMoney` / `subtractMoney` / `multiplyMoney` / `shareMoney` / `splitMoney` | functions | exact same-currency arithmetic with explicit indivisible remainder |
+| `moneyFromDecimal` / `moneyToDecimal` | functions | major units to minor ones and back, with the currency's scale as a parameter |
+| `multiplyMoneyByDecimal` / `roundMoney` | functions | an exact product rounded once, and an amount brought to a policy's steps |
+| `defineRoundingPolicy` / `roundDecimal` / `RoundingPolicySchema` / `RoundingPolicy` / `RoundingModeSchema` / `RoundingMode` | functions, schemas, _types_ | a rounding table as data, by magnitude, and its modes |
+| `DecimalStringSchema` / `DecimalInputSchema` | schemas | one canonical decimal spelling, and the input form that reaches it; a number is refused |
 | `Money` / `MoneyShare` / `MoneySplit` | _types_ | currency-literal value and remainder-bearing operation results |
 | `defineUnitSystem` / `createQuantitySchema` / `addQuantity` | functions | exact decimal quantities and caller-declared finite conversions |
 | `Quantity` / `UnitConversion` / `QuantityProjection` | _types_ | unit-literal value, rational conversion and recorded/derived provenance |
@@ -22833,6 +23158,7 @@ Server-only optional application runtime. See the
 | `AgentRuntimeRecoverOptions` | _type_ | bounded paged startup recovery with causal per-conversation scheduling, context resolver and explicit evidence policy |
 | `AgentRuntimeAbandonInput` | _type_ | one known orphan identity, expected revision and mandatory stale-owner evidence for `runtime.abandon()` |
 | `AgentRuntimeConflictError` | class | thrown when a store mutation loses to a concurrent writer — catchable by type from `stitchkit/agent-runtime` |
+| `AgentRunUnsettledError` | class | rejects `result` when the store never answered: `.run` is still active with no executor, close it with `runtime.abandon()` |
 | `AgentSessionCloseOptions` | _type_ | `gracePeriodMs` for natural settlement, then abort, then `forceTimeoutMs` for bounded settlement after it |
 | `AgentSessionCloseResult` | _type_ | what `close()` achieved: `settled`, or `timedOut` with `remaining` runs still in flight. Only omitting `forceTimeoutMs` guarantees nothing is in flight on return |
 | `AgentHistoryProjectionOptions` | _type_ | storage-neutral file resolver, explicit unresolved-file behavior, and how an interrupted turn reaches the model (`interruptedAssistant`) |
@@ -23828,7 +24154,7 @@ injected grammY bot. → ADR 0143, ADR 0201, ADR 0274 — [guide](../guide/teleg
 | `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` / `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 (a 429 pauses the token whether `send` throws it or resolves with the Bot API's `{ ok: false, … }` body), `pause`/`pauseAfter` for 429, `waitUntilResumed` for non-send retries and `stats`; it paces and never retries, and no public value carries the token |
+| `telegramOutboundBudget` / `TelegramOutboundBudget` / `TelegramOutboundBudgetConfig` / `TelegramOutboundBudgetStats` / `TelegramOutboundCallOptions` / `TelegramOutboundChatOptions` / `TelegramOutboundLane` | 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, an `interactive` lane granted before `bulk`, `run(method, payload, signal, send, { lane, maxWaitMs })` as the transformer adapter (a 429 on a send pauses its `chat_id` whether `send` throws it or resolves with the Bot API's `{ ok: false, … }` body, and refusals from `tokenPauseChats` chats pause the token), `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 |
@@ -23935,8 +24261,9 @@ the whole dependency. → ADR 0211 — [guide](../guide/telegram-screens.md)
 
 Browser-safe visitor-tracking mechanics, with no event vocabulary of their own
 and no React. The React wrapper (a provider and a hook, ~40 lines) is the
-application's — it owns the router and the session. The server half is
-`stitchkit/tracking/server`. → ADR 0166 — [guide](../guide/tracking.md)
+application's — it owns the router and the session. It imports no `zod`: the wire
+shapes are `stitchkit/tracking/contract`, the server half is
+`stitchkit/tracking/server`. → ADR 0166, ADR 0280 — [guide](../guide/tracking.md)
 
 | Export | Kind | Summary |
 |--------|------|---------|
@@ -23945,15 +24272,6 @@ application's — it owns the router and the session. The server half is
 | `TrackFn` / `EventsWithMetadata` / `EventsWithoutMetadata` | _type_ | `track(type)` / `track(type, metadata)` typed by the application's metadata map, and the two halves of that map |
 | `BuiltinTrackingEventTypes` / `CONVENTIONAL_TRACKING_EVENT_TYPES` | _type_ / const | the application's names for the events the client emits itself; the conventional `PAGE_VIEW` … `INTERACTION` set |
 | `browserTrackingHost` / `TrackingHost` / `TrackingPageContext` | function / _type_ | everything the client takes from a browser tab behind one interface — page context, visibility, scroll depth, events, intervals, clocks, storage — so a test or a non-tab host can supply its own |
-| `createTrackingContract` / `TrackingContractConfig` / `TrackingContractEndpoints` | function / _type_ | `bootstrap` (`POST /visit`) and `track` (`POST /events`, `safelistedBody`) from the application's event types, scope and optional extras |
-| `createTrackingSchemas` / `TrackingSchemas` / `TrackingSchemasConfig` | function / _type_ | every schema of one surface — `event`, `request`, `response`, `disposition`, `entry`, `bootstrap` — from `eventTypes`, optional `eventExtras`, `buildIdPattern`, `maxEventsPerBatch` |
-| `TrackingEventEnvelope` / `TrackingEventShape` | _type_ | `eventId`, `visitId`, `browserStreamId`, `browserSequence`, `type`, `page`, `metadata`, `clientTimestamp` |
-| `TrackEventsRequest` / `TrackEventsResponse` / `TrackEventsResponseSchema` | _type_ / schema | a batch (`buildId`, `events`, `utm`) and its answer (`accepted`, `dispositions`) |
-| `TrackingDisposition` / `TrackingDispositionSchema` / `TrackingDispositionStatus` / `TrackingDispositionStatusSchema` | _type_ / schema | `accepted` / `duplicate` / `identity-invalid` / `excluded-bot` — every one terminal |
-| `VisitEntryContext` / `VisitEntryContextShape` / `VisitBootstrapResponse` / `VisitBootstrapResponseSchema` | _type_ / schema | what a browser reports to open a visit (lineage, landing, referrer, UTM, display, screen, `buildId`, outbox health) and the lease it gets back |
-| `TrackingOutboxState` / `TrackingOutboxStateSchema` | _type_ / schema | `available` / `unavailable` |
-| `UtmData` / `UtmDataSchema` / `AttributionData` / `AttributionDataSchema` | _type_ / schema | campaign tags and a touch (UTM, referrer, landing page) |
-| `DEFAULT_BUILD_ID_PATTERN` | const | `dev` or a git SHA |
 | `createTrackingOutbox` / `TrackingOutbox` / `TrackingOutboxOptions` / `TrackingOutboxHealth` | function / _type_ | the tab-shared outbox: `streamId`, `reserveSequences`, `enqueue`, `acquireLease` / `releaseLease` (short, released on leave), `readBatch`, `acknowledge`, `health`; bounded by count and age |
 | `TrackingOutboxStorage` / `TrackingOutboxMeta` / `TrackingOutboxEvents` / `TrackingOutboxRecord` / `TrackingQueuedEvent` | _type_ | one atomic, all-or-nothing `transact` over a key/value store and an event store (`readonly` for pure reads) — the contract an adapter implements |
 | `indexedDbOutboxStorage` / `memoryOutboxStorage` | function | the IndexedDB adapter (one `readwrite` transaction per `transact`) and the in-memory one for tests and degraded mode |
@@ -23965,10 +24283,38 @@ application's — it owns the router and the session. The server half is
 | `createOncePerPage` / `OncePerPage` | function / _type_ | one fact per key per page within a window — the guard a twice-mounted component cannot keep itself |
 | `resolveAttribution` / `ResolveAttributionInput` / `ResolvedAttribution` / `AttributionStorage` / `ReferrerRule` | function / _type_ | first-touch once, current-touch on every new UTM; the referrer → source/medium map is the application's, there is no built-in list |
 | `parseUtmFromSearch` / `parseReferrer` | function | the two parsers `resolveAttribution` is built from |
+| `redactTrackingText` / `redactTrackingValue` | functions | mask passwords, sign-in credentials and signed launch data in text or a value of any shape; the key stays, and navigation and campaign parameters are untouched |
 | `resolveTrackedClick` / `ResolveTrackedClickOptions` / `TrackedClick` / `TrackedClickAttributes` / `ClickTarget` | function / _type_ | `data-track` → click, `data-track-action` → interaction, a link to another origin → outbound; attribute names configurable; `hrefPolicy: 'full'` retains query/fragment (default `path-only` omits them), URL credentials excluded; `leavesPage` says which path to send on |
 
 ---
 
+## `stitchkit/tracking/contract`
+
+The wire shapes of tracking, for a server and a shared contract. It brings `zod`, so
+browser code that only sends events does not import it. → ADR 0280
+
+| Export | Kind | Summary |
+|--------|------|---------|
+| `createTrackingContract` / `TrackingContractConfig` / `TrackingContractEndpoints` | function / _type_ | `bootstrap` (`POST /visit`) and `track` (`POST /events`, `safelistedBody`) from the application's event types, scope and optional extras |
+| `createTrackingSchemas` / `TrackingSchemas` / `TrackingSchemasConfig` | function / _type_ | every schema of one surface — `event`, `request`, `response`, `disposition`, `entry`, `bootstrap` — from `eventTypes`, optional `eventExtras`, `buildIdPattern`, `maxEventsPerBatch` |
+| `TrackingEventEnvelope` / `TrackingEventShape` | _type_ | `eventId`, `visitId`, `browserStreamId`, `browserSequence`, `type`, `page`, `metadata`, `clientTimestamp` |
+| `TrackEventsRequest` / `TrackEventsResponse` / `TrackEventsResponseSchema` | _type_ / schema | a batch (`buildId`, `events`, `utm`) and its answer (`accepted`, `dispositions`) |
+| `TrackingDisposition` / `TrackingDispositionSchema` / `TrackingDispositionStatus` / `TrackingDispositionStatusSchema` | _type_ / schema | `accepted` / `duplicate` / `identity-invalid` / `excluded-bot` — every one terminal |
+| `VisitEntryContext` / `VisitEntryContextShape` / `VisitBootstrapResponse` / `VisitBootstrapResponseSchema` | _type_ / schema | what a browser reports to open a visit (lineage, landing, referrer, UTM, display, screen, `buildId`, outbox health) and the lease it gets back |
+| `TrackingOutboxState` / `TrackingOutboxStateSchema` | _type_ / schema | `available` / `unavailable` |
+| `UtmData` / `UtmDataSchema` / `AttributionData` / `AttributionDataSchema` | _type_ / schema | campaign tags and a touch (UTM, referrer, landing page) |
+| `DEFAULT_BUILD_ID_PATTERN` | const | `dev` or a git SHA |
+| `PerformanceSampleSchema` / `PerformanceSample` / `PerformanceVitalsSchema` / `PerformanceVitals` | schemas / _types_ | one page load's wire shape; a metric that did not arrive is `null` |
+| `summarizePerformanceMetric` / `PerformanceMetricSummary` | function / _type_ | sample count, p75, and a p95 only from 100 samples |
+
+## `stitchkit/tracking/performance`
+
+| Export | Kind | Summary |
+|--------|------|---------|
+| `createPerformanceCollector` / `PerformanceCollector` / `PerformanceCollectorConfig` | function / _types_ | Web Vitals of this page after load: an `early` sample and a `final` beacon to `url`, undelivered ones kept for the next page; inert for a lab agent |
+| `PerformanceHost` / `VitalsLibrary` / `VitalsMetric` / `VitalsObserver` | _types_ | the seams of the collector: the page, and the part of `web-vitals` it uses |
+| `isLabUserAgent` | function | whether an agent admits to being a lab run or a crawler |
+
 ## `stitchkit/tracking/server`
 
 The decisions a tracking backend makes, without the storage it makes them
@@ -23984,6 +24330,7 @@ algorithm over a store the application implements. → ADR 0166
 | `activeIntervalOf` / `ActiveTimeInterval` / `ActiveIntervalOptions` | function / _type_ | the visible-time interval an event carries, dated by the server clock; `null` for an unshaped or implausible one |
 | `hashTrackingEvent` | function | `sha256(JSON.stringify(parsedEvent))` — the stored payload hash, unsorted on purpose so it matches what applications already hold |
 | `isBotUserAgent` / `DEFAULT_BOT_USER_AGENT_PATTERN` | function / const | crawlers, monitors and `headlesschrome` are not visitors |
+| `trackingTelemetryHealth` / `TrackingOutboxReport` / `TrackingTelemetryHealth` | function / _types_ | `ok`, `degraded` or `unknown` from outbox reports; a lifetime `dropped` counts only by what it grew over `baselines` |
 | `createPresenceRegistry` / `PresenceRegistry` / `PresenceEntry` | function / _type_ | who is here now, in this process: `touch` / `snapshot(filter)` / `presentVisitOf` with a 45 s TTL |
 
 ---
@@ -24022,6 +24369,15 @@ providers, the microphone and the player remain application-owned. See the
 
 ---
 
+## `stitchkit/xlsx`
+
+| Export | Kind | Summary |
+|--------|------|---------|
+| `renderXlsx` | function | a workbook from rows and typed columns as XLSX bytes; deterministic, no formula in the file |
+| `XLSX_MEDIA_TYPE` | constant | the media type for `defineExportOperation` and a download response |
+| `XlsxCellError` | class | a value of the wrong type, or one Excel cannot hold exactly, with the cell's address |
+| `XlsxWorkbookSchema` / `XlsxWorkbook` / `XlsxSheetSchema` / `XlsxColumnSchema` / `XlsxColumn` | schemas / _types_ | the workbook, its sheets and the six column types |
+
 ## `stitchkit/geo`
 
 Server-only managed GeoIP generations. Applications own database acquisition,