stitchkit 0.115.0 → 0.117.0

package/dist/xlsx/schema.d.ts

@@ -0,0 +1,119 @@
+import { z } from 'zod';
+export declare const XlsxColumnSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    key: z.ZodString;
+    header: z.ZodString;
+    width: z.ZodOptional<z.ZodNumber>;
+    type: z.ZodLiteral<"text">;
+}, z.core.$strip>, z.ZodObject<{
+    key: z.ZodString;
+    header: z.ZodString;
+    width: z.ZodOptional<z.ZodNumber>;
+    type: z.ZodLiteral<"number">;
+    format: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>, z.ZodObject<{
+    key: z.ZodString;
+    header: z.ZodString;
+    width: z.ZodOptional<z.ZodNumber>;
+    type: z.ZodLiteral<"date">;
+}, z.core.$strip>, z.ZodObject<{
+    key: z.ZodString;
+    header: z.ZodString;
+    width: z.ZodOptional<z.ZodNumber>;
+    type: z.ZodLiteral<"datetime">;
+    timeZone: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    key: z.ZodString;
+    header: z.ZodString;
+    width: z.ZodOptional<z.ZodNumber>;
+    type: z.ZodLiteral<"money">;
+    currency: z.ZodString;
+    scale: z.ZodNumber;
+}, z.core.$strip>, z.ZodObject<{
+    key: z.ZodString;
+    header: z.ZodString;
+    width: z.ZodOptional<z.ZodNumber>;
+    type: z.ZodLiteral<"boolean">;
+}, z.core.$strip>], "type">;
+export type XlsxColumn = z.infer<typeof XlsxColumnSchema>;
+export declare const XlsxSheetSchema: z.ZodObject<{
+    name: z.ZodString;
+    columns: z.ZodReadonly<z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        key: z.ZodString;
+        header: z.ZodString;
+        width: z.ZodOptional<z.ZodNumber>;
+        type: z.ZodLiteral<"text">;
+    }, z.core.$strip>, z.ZodObject<{
+        key: z.ZodString;
+        header: z.ZodString;
+        width: z.ZodOptional<z.ZodNumber>;
+        type: z.ZodLiteral<"number">;
+        format: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>, z.ZodObject<{
+        key: z.ZodString;
+        header: z.ZodString;
+        width: z.ZodOptional<z.ZodNumber>;
+        type: z.ZodLiteral<"date">;
+    }, z.core.$strip>, z.ZodObject<{
+        key: z.ZodString;
+        header: z.ZodString;
+        width: z.ZodOptional<z.ZodNumber>;
+        type: z.ZodLiteral<"datetime">;
+        timeZone: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        key: z.ZodString;
+        header: z.ZodString;
+        width: z.ZodOptional<z.ZodNumber>;
+        type: z.ZodLiteral<"money">;
+        currency: z.ZodString;
+        scale: z.ZodNumber;
+    }, z.core.$strip>, z.ZodObject<{
+        key: z.ZodString;
+        header: z.ZodString;
+        width: z.ZodOptional<z.ZodNumber>;
+        type: z.ZodLiteral<"boolean">;
+    }, z.core.$strip>], "type">>>;
+    rows: z.ZodReadonly<z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+}, z.core.$strip>;
+export declare const XlsxWorkbookSchema: z.ZodObject<{
+    sheets: z.ZodReadonly<z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        columns: z.ZodReadonly<z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+            key: z.ZodString;
+            header: z.ZodString;
+            width: z.ZodOptional<z.ZodNumber>;
+            type: z.ZodLiteral<"text">;
+        }, z.core.$strip>, z.ZodObject<{
+            key: z.ZodString;
+            header: z.ZodString;
+            width: z.ZodOptional<z.ZodNumber>;
+            type: z.ZodLiteral<"number">;
+            format: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>, z.ZodObject<{
+            key: z.ZodString;
+            header: z.ZodString;
+            width: z.ZodOptional<z.ZodNumber>;
+            type: z.ZodLiteral<"date">;
+        }, z.core.$strip>, z.ZodObject<{
+            key: z.ZodString;
+            header: z.ZodString;
+            width: z.ZodOptional<z.ZodNumber>;
+            type: z.ZodLiteral<"datetime">;
+            timeZone: z.ZodString;
+        }, z.core.$strip>, z.ZodObject<{
+            key: z.ZodString;
+            header: z.ZodString;
+            width: z.ZodOptional<z.ZodNumber>;
+            type: z.ZodLiteral<"money">;
+            currency: z.ZodString;
+            scale: z.ZodNumber;
+        }, z.core.$strip>, z.ZodObject<{
+            key: z.ZodString;
+            header: z.ZodString;
+            width: z.ZodOptional<z.ZodNumber>;
+            type: z.ZodLiteral<"boolean">;
+        }, z.core.$strip>], "type">>>;
+        rows: z.ZodReadonly<z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+    }, z.core.$strip>>>;
+}, z.core.$strip>;
+export type XlsxWorkbook = z.input<typeof XlsxWorkbookSchema>;
+//# sourceMappingURL=schema.d.ts.map

package/dist/xlsx/schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../../src/xlsx/schema.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAmBxB,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;2BAqB3B,CAAC;AACH,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAK1D,eAAO,MAAM,eAAe;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAQ1B,CAAC;AAEH,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAU7B,CAAC;AACH,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC"}

package/dist/xlsx/zip.d.ts

@@ -0,0 +1,13 @@
+/**
+ * The ZIP container an XLSX is: deflated entries, no directories, no extras.
+ *
+ * Written here rather than taken from a library because the package has one
+ * runtime dependency and this format needs about a hundred lines. Compression
+ * goes through the platform's `CompressionStream`. Entry times are the format's
+ * epoch, so the same workbook always produces the same bytes.
+ */
+export declare function zip(entries: readonly {
+    readonly name: string;
+    readonly content: string;
+}[]): Promise<Uint8Array>;
+//# sourceMappingURL=zip.d.ts.map

package/dist/xlsx/zip.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"zip.d.ts","sourceRoot":"","sources":["../../src/xlsx/zip.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAuDH,wBAAsB,GAAG,CACvB,OAAO,EAAE,SAAS;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CAAE,EAAE,GACtE,OAAO,CAAC,UAAU,CAAC,CA8DrB"}

package/llms/agent-runtime.2.txt

@@ -237,6 +237,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
@@ -837,19 +877,3 @@ reconcile.
 
 The sink deduplicates stable event IDs by default. Cross-crash exactly-once still requires a durable
 outbox.
-
-## Deterministic race and adapter proof
-
-`stitchkit/agent-runtime/testing` exports `createAgentRaceBarrier`, `createAgentRaceDriver`,
-`createAgentRaceTrace` and `runAgentStoreConformance` — agent testing tools live beside the agent
-runtime, and `stitchkit/testing` imports none of it. Barriers have bounded teardown, traces assert exact partial order, and the
-helpers are exercised from packed Bun and Node consumers. `runAgentStoreConformance` runs duplicate,
-coalescing, collision, stale checkpoint, replay safety, terminal race, absorption, bounded reads,
-causal queued-history order, durable interrupt priority, compaction and recovery invariants against
-any fresh durable adapter.
-
-It picks its conversation identities itself and passes them to `createStore(context)` **before the
-first mutation**, so an adapter whose runtime rows reference an application-owned conversation row
-can provision those parents; the optional `cleanup(context)` removes them again, and runs once
-whether the scenario passed or failed. A factory that owns no fixture state ignores the argument and
-keeps working unchanged.

package/llms/agent-runtime.3.txt

@@ -12,6 +12,22 @@ Parts of this slice:
 # Guide: Agent application runtime  (docs/guide/agent-runtime.md)  (continued)
 ==============================================================================
 
+## Deterministic race and adapter proof
+
+`stitchkit/agent-runtime/testing` exports `createAgentRaceBarrier`, `createAgentRaceDriver`,
+`createAgentRaceTrace` and `runAgentStoreConformance` — agent testing tools live beside the agent
+runtime, and `stitchkit/testing` imports none of it. Barriers have bounded teardown, traces assert exact partial order, and the
+helpers are exercised from packed Bun and Node consumers. `runAgentStoreConformance` runs duplicate,
+coalescing, collision, stale checkpoint, replay safety, terminal race, absorption, bounded reads,
+causal queued-history order, durable interrupt priority, compaction and recovery invariants against
+any fresh durable adapter.
+
+It picks its conversation identities itself and passes them to `createStore(context)` **before the
+first mutation**, so an adapter whose runtime rows reference an application-owned conversation row
+can provision those parents; the optional `cleanup(context)` removes them again, and runs once
+whether the scenario passed or failed. A factory that owns no fixture state ignores the argument and
+keeps working unchanged.
+
 ## Plain completions and shared invocation receipts
 
 Use `createModelInvocationLedger` from `stitchkit/agent-runtime` when a direct text
@@ -191,6 +207,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`) |

package/llms/agent-runtime.txt

@@ -314,8 +314,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`
@@ -420,7 +420,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({

package/llms/cli.txt

@@ -670,7 +670,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.

package/llms/primitives.txt

@@ -60,6 +60,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
@@ -172,6 +189,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 |

package/llms/stitchkit.txt

@@ -60,7 +60,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 |
@@ -75,24 +75,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 |
@@ -104,7 +107,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 |

package/llms/telegram.txt

@@ -122,19 +122,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.
@@ -146,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
@@ -608,7 +635,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 |

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 |
 
 ---