stitchkit 0.116.0 → 0.118.0

package/llms/telegram.txt

@@ -131,17 +131,37 @@ cast, and a send cancelled in the queue then waits for its slot and fails as
   `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 concerns that call and pauses nothing; `budget.pauseAfter`
-  remains for a caller who decides otherwise. 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.
@@ -153,9 +173,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
@@ -458,7 +478,17 @@ intake recorded the body; the handler runs after, outside the request. Updates
 of one chat run in order, other chats alongside (`maxConcurrent`, 32). An
 attempt holds a lease it renews while the handler lives; a sweep takes over what
 was left — `pending` whose process never got to it (`pendingGraceMs`), `failed`
-whose retry is due, `processing` whose process died. A failure is retried with
+whose retry is due, `processing` whose process died. `start` schedules the whole
+queue the last process left, page by page and without waiting for
+`pendingGraceMs`, and an update accepted meanwhile takes its place behind it, so
+a crash keeps each chat in order however long the queue was. The queue sits in
+memory while it drains, as it did in the process that accepted it. `close`
+waits for the handlers running and leaves the rest of the queue recorded. Order
+holds inside one process for updates handled in their turn: the attempt a crash
+interrupted comes when its lease lapses, a failed update at its retry and one
+the store refused to claim at a later sweep, each after later updates of its
+chat. An old release draining beside a new one shares its queue, so the two can
+run updates of one chat side by side. A failure is retried with
 backoff or after Telegram's `retry_after`; one Telegram said repeating cannot
 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
@@ -508,7 +538,8 @@ 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 base store remains the six atomic steps of `TelegramUpdateStore`. A
+The base store remains the six atomic steps of `TelegramUpdateStore`; `due` is
+paged, continuing strictly after `afterUpdateId`. A
 `TelegramUpdateFencedStore` adds `claimOwned`, `renewOwned`, `owns` and
 `settleOwned`; `TelegramUpdateDurableStore` adds the final-obligation methods.
 Reference stores implement both, so the bot's own database holds the fence and
@@ -615,7 +646,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` / `TelegramOutboundCallOptions` / `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 })` as the transformer adapter (a 429 on a send 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 |
@@ -639,7 +670,7 @@ injected grammY bot. → ADR 0143, ADR 0201, ADR 0274 — [guide](../guide/teleg
 | `TelegramUpdateIntakeConfig` / `TelegramUpdateAttemptIntakeConfig` / `TelegramUpdateIntakeOptions` / `TelegramUpdateIntake` / `TelegramUpdateEnvelope` / `TelegramUpdateFailure` / `TelegramUpdateStoreStep` | _type_ | `store`, unchanged `handle(update)` or attempt-aware `handleAttempt(update, context)` (a grammY `BotError` is unwrapped), shared `retry`, `maxAttempts` (5), `leaseMs` (120 000), `pendingGraceMs` (60 000), `sweepEveryMs` (30 000), `retainMs` (24 h), `maxConcurrent` (32), `onFailure`, durable `handleExhaustion`, `onExhaustionFailure`, `onStoreError`, `now`; `accept(body)`, `start()`, `sweep()`, `idle()`, `close()` |
 | `TelegramUpdateAttemptContext` / `TelegramUpdateAttemptIdentity` / `TelegramUpdateOwnershipLostError` | _type_ / class | immutable `{ updateId, attempt, claimId }` fence plus `ownerLost`; the persisted opaque claim token prevents a stale capability from matching after prune/re-add, while a store check in the consumer's DB transaction fences a domain write |
 | `TelegramUpdateExhaustion` / `TelegramUpdateExhaustionFailure` / `StoredTelegramUpdateExhaustion` / `TelegramUpdateExhaustionQuery` | _type_ | a terminal update/attempt/error retained in the update store until `handleExhaustion` resolves; ordered `{ limit, afterUpdateId? }` pages prevent a failing first batch from starving later rows; delivery failures are observational and leave it due |
-| `TelegramUpdateStore` / `StoredTelegramUpdate` / `TelegramUpdateState` / `TelegramUpdateSettlement` / `TelegramUpdateClaimOptions` / `TelegramUpdateDueQuery` | _type_ | the base 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 |
+| `TelegramUpdateStore` / `StoredTelegramUpdate` / `TelegramUpdateState` / `TelegramUpdateSettlement` / `TelegramUpdateClaimOptions` / `TelegramUpdateDueQuery` | _type_ | the base 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; `due` returns one page and continues strictly after `afterUpdateId` |
 | `TelegramUpdateFencedStore` / `TelegramUpdateDurableStore` | _type_ | reference-store capabilities: `claimOwned` creates and returns the persisted identity, `renewOwned`, `owns(identity, at)` and `settleOwned(identity, settlement)` act only on that exact unexpired claim; `exhaust`, `dueExhaustions`, `acknowledgeExhaustion` keep a final consumer obligation in the same row until exact acknowledgement |
 | `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 |

package/llms/tracking-contract.txt

@@ -0,0 +1,32 @@
+# stitchkit/tracking/contract — 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: API reference: `stitchkit/tracking/contract`  (docs/api/reference.md)
+
+Also read:
+- see `llms/tracking.txt` for the Visitor tracking guide
+
+==============================================================================
+# API reference: `stitchkit/tracking/contract`  (docs/api/reference.md)
+==============================================================================
+
+## `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 |

package/llms/tracking-performance.txt

@@ -0,0 +1,21 @@
+# stitchkit/tracking/performance — 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: API reference: `stitchkit/tracking/performance`  (docs/api/reference.md)
+
+Also read:
+- see `llms/tracking.txt` for the Visitor tracking guide
+
+==============================================================================
+# API reference: `stitchkit/tracking/performance`  (docs/api/reference.md)
+==============================================================================
+
+## `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 |

package/llms/tracking-server.txt

@@ -27,6 +27,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 |
 
 ---

package/llms/tracking.txt

@@ -33,7 +33,7 @@ Both entrypoints are **evolving**.
 ## Contract
 
 ```ts
-import { createTrackingContract } from 'stitchkit/tracking'
+import { createTrackingContract } from 'stitchkit/tracking/contract'
 
 export const tracking = createTrackingContract({
   scope: 'public',
@@ -232,6 +232,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
@@ -246,8 +316,9 @@ looks different even though their mechanics are now one.
 
 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 |
 |--------|------|---------|
@@ -256,15 +327,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 |
@@ -276,6 +338,7 @@ 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 |
 
 ---

package/llms/{upgrading-0.105.0-0.116.0.txt → upgrading-0.105.0-0.118.0.txt}

@@ -1,14 +1,84 @@
-# Upgrading 0.105.0 → 0.116.0 — stitchkit docs slice
+# Upgrading 0.105.0 → 0.118.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.105.0 → 0.116.0  (docs/guide/upgrading.md)
+Contains: Guide: Upgrading, 0.105.0 → 0.118.0  (docs/guide/upgrading.md)
 
 ==============================================================================
-# Guide: Upgrading, 0.105.0 → 0.116.0  (docs/guide/upgrading.md)
+# Guide: Upgrading, 0.105.0 → 0.118.0  (docs/guide/upgrading.md)
 ==============================================================================
 
+## Released migration: 0.118.0
+
+### telegram-due-cursor
+
+**Who must act:** an application with its own `TelegramUpdateStore`. A bot on `memoryTelegramUpdateStore`,
+`sqliteTelegramUpdateStore` or `postgresTelegramUpdateStore` needs no change.
+
+`due` returns one page of a queue whose rows stay due until claimed, and the intake reads the next page from
+`afterUpdateId`, until a page comes back empty. A store that ignores the cursor fails `start` and every sweep
+with a `TypeError`, reported to `onStoreError`, as soon as a row is due. Continue strictly after it, in
+`update_id` order:
+
+```ts
+// before
+where: { OR: dueRows }
+// after
+where: { OR: dueRows, ...(query.afterUpdateId !== undefined && { updateId: { gt: query.afterUpdateId } }) }
+```
+
+`checkTelegramUpdateStore` reports the rule as `due continues strictly after its cursor`.
+
+Search pattern: an object with a `due(` method passed as `store` to `createTelegramUpdateIntake`.
+
+## 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

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.105.0 → 0.116.0: `llms/upgrading-0.105.0-0.116.0.txt`
+- 0.105.0 → 0.118.0: `llms/upgrading-0.105.0-0.118.0.txt`
 - 0.84.0 → 0.104.0: `llms/upgrading-0.84.0-0.104.0.txt`
 - 0.63.0 → 0.83.0: `llms/upgrading-0.63.0-0.83.0.txt`
 - 0.44.0 → 0.62.0: `llms/upgrading-0.44.0-0.62.0.txt`

package/llms/xlsx.txt

@@ -0,0 +1,107 @@
+# stitchkit/xlsx — 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: XLSX  (docs/guide/xlsx.md) · API reference: `stitchkit/xlsx`  (docs/api/reference.md)
+
+==============================================================================
+# 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.
+
+==============================================================================
+# API reference: `stitchkit/xlsx`  (docs/api/reference.md)
+==============================================================================
+
+## `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 |