stitchkit 0.107.0 → 0.108.1

package/llms-full.txt

@@ -62,9 +62,9 @@ own, recorded as an ADR.
 | `stitchkit/cli/publish` | build and release tooling (Bun or Node, POSIX) | evolving | `publishCli` — commit a verified CLI distribution and move its public manifest last; see [CLI guide](cli.md#publishing-a-complete-version) |
 | `stitchkit/remote` | browser **and** server | stable | peer-free `implementRemote` for thin HTTP proxy processes |
 | `stitchkit/process` | server (Bun or Node, POSIX) | evolving | finite native commands, byte sinks, bounded capture and process-group cancellation |
-| `stitchkit/files/packaging` | build time (Bun or Node) | evolving | installed native asset graph, integrity and Bun packaging plugin; no runtime install policy |
+| `stitchkit/files/packaging` | build time (Bun or Node) | evolving | installed native asset graph, integrity, Bun packaging plugin and the artifact loader check; no runtime install policy |
 | `stitchkit/files` | server (Bun or Node) | stable | peer-free managed local-file boundary |
-| `stitchkit/telegram` | server (Bun or Node) | evolving | peer-free Telegram platform primitives — Mini App `initData` verification, send-failure classification, resumable broadcasts, the operator channel with dedupe, local Bot API files, webhook ownership and durable webhook update intake |
+| `stitchkit/telegram` | server (Bun or Node) | evolving | peer-free Telegram platform primitives — Mini App `initData` verification, send-failure classification, resumable broadcasts, the operator channel with dedupe, a Bot API transport that separates a request that never left from an unknown outcome, local Bot API files, webhook ownership and durable webhook update intake |
 | `stitchkit/telegram/html` | browser and server | evolving | Telegram's HTML as a tree — clean any markup to what Telegram accepts, cut long text into valid parts by what the reader sees, check markup before it is sent |
 | `stitchkit/telegram/screens` | server (Bun or Node) | evolving | a bot's menus as declared screens over grammY — typed paths, actions and input, message reconciliation, state in any `StorageAdapter`, a test chat |
 | `stitchkit/tracking` | browser **and** server | evolving | visitor-tracking mechanics — `createTrackingClient`, the tab-shared outbox, the page-leave beacon, attribution, the contract factory; no event vocabulary, no React |
@@ -74,12 +74,12 @@ own, recorded as an ADR.
 | `stitchkit/geo` | server (Bun or Node) | evolving | managed GeoIP reader generations, last-known-good reload and the optional MaxMind adapter |
 | `stitchkit/oauth` | browser **and** server | evolving | provider-neutral Authorization Code + PKCE request and one-shot callback transaction mechanics |
 | `stitchkit/google` | server (Bun or Node) | evolving | optional Google code exchange and verified OIDC identity adapter |
-| `stitchkit/observability` | server | stable<br>_redefined in 2 of the 52 minors since 0.56.2, most recently 0.92.0_ | request/tool event projections — `createObservability`, trace context, sanitisation |
-| `stitchkit/testing` | tests on Bun or Node | stable | in-process generated clients over a real Fetch handler, plus the managed-resource conformance kit |
+| `stitchkit/observability` | server | stable<br>_redefined in 2 of the 53 minors since 0.56.2, most recently 0.92.0_ | request/tool event projections — `createObservability`, trace context, sanitisation |
+| `stitchkit/testing` | tests on Bun or Node | stable | in-process generated clients over a real Fetch handler, the managed-resource conformance kit and manual time for schedules and retries |
 | `stitchkit/declaration` | browser + build and deployment tooling (Bun or Node) | evolving | `ProjectDeclarationSchema` — the one machine-readable statement a repository makes about itself |
 | `stitchkit/react` | browser + server rendering | stable | `createCursorQuery`, `createCacheBridge`, QueryClient and `ApiError` retry policy |
 | `stitchkit/react/keyboard` | browser | evolving | which part of a screen gets a key — ordered layers, one Escape per level, list zones with real focus; see [keyboard guide](keyboard.md) |
-| `stitchkit/agent-runtime` | server | evolving<br>_redefined in 23 of the 52 minors since 0.56.2, most recently 0.105.0_ | optional durable conversation/run loop, history, models, prompts, fencing and events |
+| `stitchkit/agent-runtime` | server | evolving<br>_redefined in 23 of the 53 minors since 0.56.2, most recently 0.105.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 |
@@ -91,7 +91,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 13 of the 52 minors since 0.56.2, most recently 0.105.0_ | managed resource graph, readiness, admission, schedules, subtree restart and bounded shutdown |
+| `stitchkit/application` | browser + server | evolving<br>_redefined in 13 of the 53 minors since 0.56.2, most recently 0.105.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 |
@@ -3403,6 +3403,47 @@ Set `finalLine: 'require-newline'` when the final newline is part of the
 protocol's truncation proof. The default `allow` continues to accept one valid
 final JSON document without a newline.
 
+### Any byte source
+
+`parseNDJSON` (and `parseSSE`) read more than a `Response`: a `ReadableStream<Uint8Array>`
+(a fetch body, a Bun child's `stdout`) or any `AsyncIterable<Uint8Array>` (a Node child's
+`stdout`). `signal` stops reading and cancels or returns the source:
+
+```ts
+import { parseNDJSON } from 'stitchkit'
+
+const child = Bun.spawn(['worker'], { stdout: 'pipe' })
+for await (const progress of parseNDJSON(child.stdout, {
+  maxLineBytes: 64 * 1024,
+  finalLine: 'require-newline',
+})) report(progress)
+```
+
+A source that hands over bytes through a callback — a `Bun.listen` or `Bun.connect` socket's
+`data` handler — uses `createNDJSONDecoder`, the same reader driven by pushes:
+
+```ts
+import { createNDJSONDecoder } from 'stitchkit'
+
+const decoder = createNDJSONDecoder<ControlRequest>({ maxLineBytes: 16 * 1024 })
+Bun.listen({
+  unix: socketPath,
+  socket: {
+    data(socket, bytes) {
+      for (const request of decoder.push(bytes)) handle(socket, request)
+    },
+  },
+})
+```
+
+Use one decoder per connection. Lines are split in bytes and decoded only once complete, so a
+character split across chunks is never torn. A line that crosses `maxLineBytes` throws
+`StreamLineLimitError` (`limitBytes`, `lineBytes`) at the chunk that crossed it: the reader
+retains at most the limit, however long the line. With `finalLine: 'require-newline'`, a source
+that ends inside a line throws `StreamTruncatedLineError` (`lineBytes`) instead of yielding the
+fragment as a value — the right policy for a socket or a child process, where a missing newline
+means the writer died. Both errors extend the `RangeError` / `SyntaxError` they replace.
+
 ## Resumable streams
 
 A stream that survives a dropped connection needs four things beyond opening it:
@@ -8606,11 +8647,20 @@ spool never load it, on any operating system. The package is free of import side
 
 Check an artifact by its loader, never by whether it holds `.node` bytes: Bun can copy the addon
 into a compiled executable even without the plugin, and the unpackaged loader does not use it.
-Search the artifact for `STITCHKIT_NATIVE_NOT_PACKAGED` in both latin1 and UTF-16LE, because Bun
-stores source text with non-ASCII characters as UTF-16. Present: the unpackaged loader is inside,
-and every call above refuses on macOS. Absent in a plugin build: the static loader is inside
-(`/$bunfs/root/darwin-<arch>-<hash>.node` in an executable, the companion path in a JS build).
-Absent without the plugin: nothing in the artifact needs the addon.
+`inspectNativeArtifact(bytes)` from `stitchkit/files/packaging` reads the marker every generated
+loader carries and answers `packaged` (the plugin's static loader is inside), `unpackaged` (the
+default loader is inside, and every call above refuses on macOS) or `no-loader` (nothing in the
+artifact loads the addon). It reads both latin1 and UTF-16LE, because Bun stores source text with
+non-ASCII characters as UTF-16, and it does not mistake the `STITCHKIT_NATIVE_NOT_PACKAGED` error
+code, which every bundle with a lock carries, for a loader. Artifacts built by 0.107.0 or earlier
+carry no marker and read `no-loader`.
+
+```ts
+import { inspectNativeArtifact } from 'stitchkit/files/packaging'
+
+const loader = inspectNativeArtifact(await Bun.file('dist/cli').bytes())
+if (loader === 'unpackaged') throw new Error('dist/cli was built without native packaging')
+```
 
 ```sh
 bun build src/native.ts --target=bun --minify --outfile=dist/native.js
@@ -8690,6 +8740,11 @@ addon path accepts. `entryPath` is fixed, without
 Bun naming templates such as `[dir]` or `[name]`. Companion JS builds require one entry, no splitting,
 and `naming.entry` exactly matching `entryPath`; the plugin rejects a mismatching layout.
 Choose any application layout; the framework does not prescribe an app directory or installer.
+The plugin packages the loader of the installation it was created from. A build whose entry
+imports another `stitchkit` installation — another version, or the same version under another
+path, as when a build tool carries its own copy — fails with an error naming both versions and
+roots: that installation's loader would refuse the addon at run time, so the artifact is never
+written. Call `createNativePackaging` from the `stitchkit` the entry imports.
 Keep every bundler output and write `asset.bytes`; never read the addon from `node_modules` a
 second time. An installed addon whose size or SHA256 differs from the published manifest refuses
 with `mismatch` / `NATIVE_ASSET_DIGEST_MISMATCH`, so a file substituted after installation never
@@ -13922,6 +13977,50 @@ The suite in `packages/core/tests` is the working reference for testing each
 piece. Its size changes with the public surface, so the guide does not pin a
 count that can drift independently from the test runner.
 
+### Manual time for schedules and retries
+
+`createManualClock()` from `stitchkit/testing` stands time still until the test moves it. It is
+the `clock` of `createManagedSchedule`, a durable sleep, a revision signal or bounded admission,
+and the `schedule` a retrier of your own takes:
+
+```ts
+import { createManagedSchedule } from 'stitchkit/application'
+import { createManualClock } from 'stitchkit/testing'
+
+const clock = createManualClock()
+const schedule = createManagedSchedule({ id: 'sweep', everyMs: 1_000, clock, run })
+// …start and activate it…
+await clock.advance(3_500) // runs at 1 s, 2 s and 3 s of manual time; the test takes milliseconds
+```
+
+Only one `advance` (or `until`) runs at a time; a second one started before the first settled is
+refused, because two interleaved moves would run time backwards.
+
+Due timers fire in deadline order, ties in scheduling order. After each firing the clock yields
+real event-loop turns, not just microtasks: a continuation that arms the next retry after an
+already-readable socket or another macrotask has armed it before the clock moves on, so
+`advance(10_000)` does not skip a retry armed at the fifth second. Real work of unknown length —
+a request to a fake server, a hash in the thread pool — outruns any number of turns; the test
+wraps the dependency it injects in a `hold`:
+
+```ts
+const request = async (body) => {
+  const held = clock.hold('upload to the fake server')
+  try {
+    return await fakeServer.send(body)
+  } finally {
+    held.release()
+  }
+}
+```
+
+Time does not move while a hold is open; past `holdLimitMs` of real time (default 5 s)
+`advance` fails with `ManualClockError` `MANUAL_CLOCK_HOLD_TIMEOUT`, naming every open hold. A
+held operation that waits for the clock itself — a request timing out on a deadline — `park`s
+its hold so the deadline can come. `until(done)` moves from deadline to deadline until `done()`
+holds and fails with `MANUAL_CLOCK_LIMIT` past `limitMs` of manual time; `pending()` counts the
+timers still waiting, so a timer leaked past `close()` shows as a number, not as a hang.
+
 ### Managed-resource conformance
 
 Consumer-owned resource adapters can run the framework's deterministic
@@ -15015,8 +15114,8 @@ and pacing/progress intervals must fit native timers. The optional
 when the signal aborts if a custom sleeper ignores it. A send already in flight
 finishes and is recorded before stopping.
 
-Without `classify`, known Bot API 429, unreachable-recipient, malformed-message
-and server-error behavior remains. Unknown/no-status failures now halt as
+Without `classify`, known Bot API 429, unreachable-recipient, malformed-message,
+server-error and not-dispatched behavior remains. Unknown/no-status failures now halt as
 uncertain, rather than being automatically retried. Existing custom `send`
 implementations that relied on those retries must supply an explicit classifier
 for proven pre-effect failures. `report.halt` now carries
@@ -15035,6 +15134,36 @@ The installed
 fixture checks injected rate limits, ambiguity/no resend, wait budgets and abort
 on Bun and Node without a client SDK.
 
+## A transport that knows whether a request left
+
+`fetch` folds establishing the connection and waiting for the answer into one failure. From that
+failure nobody can say whether Telegram saw the message, so the senders above treat every network
+failure as unknown: a broadcast records the recipient `uncertain` and the operator channel drops
+the message rather than risk a duplicate. On a route that sometimes fails to connect at all, that
+loses messages that never left.
+
+`createTelegramBotTransport()` connects first and writes the request only on an established
+connection. Every failure before the first byte is written is `TelegramNotDispatchedError`
+(`stage`: `lookup`, `connect` or `request`), and `classifyTelegramSendFailure` reads it as
+`not-dispatched` — `retryable`, with `evidence: 'transport'`. A broadcast retries it as
+`transient`; the operator channel sends it again. A failure after the request was written stays
+an outcome nobody can know.
+
+```ts
+import { createTelegramBotTransport, telegramOperatorSender } from 'stitchkit/telegram'
+
+const transport = createTelegramBotTransport()
+const send = telegramOperatorSender({ token: env.BOT_TOKEN, fetch: transport })
+```
+
+Pass it as `fetch` to `callTelegramBotApi`, `telegramBroadcastSender`, `telegramOperatorSender`
+or the webhook calls. Addresses come in the system resolver's order with no family forced; the
+next address starts 250 ms later (Happy Eyeballs), and a round with no connection is repeated
+with new sockets inside `connectBudgetMs` (default 5 s, which also bounds the address lookup; each
+round waits `connectAttemptMs`, default 2 s). The answer must arrive within `responseTimeoutMs` (default 30 s) and fit
+`maxResponseBytes` (default 1 MiB). It speaks HTTP/1.1 over `https:`, and over `http:` for a
+local Bot API server, and it uses no proxy: where the network needs one, keep `fetch`.
+
 ## Message markup
 
 `stitchkit/telegram/html` is Telegram's HTML parse mode as a tree, with no peer
@@ -15622,6 +15751,62 @@ analytics policy belong to the application.
 
 # Upgrading stitchkit
 
+## Released migration: 0.108.0
+
+### a request that never left is its own send outcome
+
+**Who must act:** code with an exhaustive `switch` or `Record` over `TelegramSendFailureReason` or
+over `TelegramSendFailure['evidence']` (`stitchkit/telegram`). Code that reads `retryable` and
+`recipientUnreachable` needs no change.
+
+`classifyTelegramSendFailure` now returns `reason: 'not-dispatched'` with `evidence: 'transport'`
+for a `TelegramNotDispatchedError`: the request never left, so it is `retryable` and repeating it
+cannot duplicate a message
+([ADR 0253](../decisions/0253-a-telegram-request-that-never-left-is-safe-to-repeat.md)). Only
+`createTelegramBotTransport` throws that error; with the default `fetch` nothing changes at run time.
+
+1. Add the reason and the evidence to every exhaustive mapping:
+
+   ```ts
+   // before
+   const code: Record<TelegramSendFailureReason, string> = { /* … */ unknown: 'E_UNKNOWN' }
+   // after
+   const code: Record<TelegramSendFailureReason, string> = {
+     /* … */ 'not-dispatched': 'E_NOT_SENT', unknown: 'E_UNKNOWN',
+   }
+   ```
+
+   Search pattern: `TelegramSendFailureReason`, `TELEGRAM_SEND_FAILURE_REASONS` and `evidence ===`.
+2. Type-check: a `Record` or an exhaustive `switch` without the new members fails to compile.
+3. To use the distinction, pass `fetch: createTelegramBotTransport()` to the senders that need it
+   (see the [Telegram guide](telegram.md#a-transport-that-knows-whether-a-request-left)).
+
+### a packaging plugin packages only its own installation
+
+**Who must act:** builds that call `createNativePackaging` (`stitchkit/files/packaging`) from a
+`stitchkit` installation other than the one the bundled entry imports — typically a build tool that
+carries its own copy. Builds whose entry and plugin come from one installation are unchanged.
+
+Such a build used to succeed and ship the other installation's default Darwin loader, which refuses
+the addon on macOS at run time. It now fails, naming both versions and roots
+([ADR 0254](../decisions/0254-a-packaging-plugin-owns-one-loader-and-names-what-it-finds.md)).
+
+1. Create the plugin from the `stitchkit` the entry resolves, not from the build tool's copy:
+
+   ```ts
+   // before: the build tool's own stitchkit
+   import { createNativePackaging } from 'stitchkit/files/packaging'
+   // after: resolved from the project that owns the entry
+   const { createNativePackaging } = await import(
+     Bun.resolveSync('stitchkit/files/packaging', projectRoot)
+   )
+   ```
+
+   Search pattern: `createNativePackaging` in build tooling that is installed apart from the project.
+2. Check the artifact with `inspectNativeArtifact`: a correct build reads `packaged`. An artifact
+   built by 0.107.0 or earlier carries no loader marker and reads `no-loader` whatever it holds, so
+   rebuild before relying on the check; a test of `=== 'unpackaged'` alone passes such an artifact.
+
 ## Released migration: 0.107.0
 
 ### embedded native packaging names no paths
@@ -16871,6 +17056,38 @@ of the range if you want a different one.
 So upgrading is: read the `### ⚠️ Breaking changes` of every version *above* your
 current one *up to* your target, and apply each snippet.
 
+### Does an item touch your project?
+
+Every breaking item since 0.104.0 carries one machine line, `**Affects:**`, naming what it changes
+in a form that is read without guessing from prose:
+
+```md
+**Affects:** `stitchkit/files/packaging` createNativePackaging(delivery: 'embedded')
+**Affects:** `stitchkit/contract`, `stitchkit/server` AppError; `stitchkit` ApiError
+**Affects:** `stitchkit/process` behaviour
+**Affects:** `stitchkit/agent-runtime/harness-tools` *
+```
+
+Targets are separated by `; `. Each starts with one or more backticked entrypoints, then lists the
+exports it changes (an optional parenthesised qualifier names the option or member), or says
+`behaviour` for a change of semantics no import name reveals, or `*` for every import of a removed
+entrypoint. `stitchkit upgrade` reads your project's imports (`--cwd`, default `.`; TypeScript, JavaScript,
+Vue and Svelte files; not `node_modules`, and not a `dist`, `build`, `out` or `coverage` folder
+beside a `package.json`, which is build output) and gives each item one verdict:
+
+- **affects this project** — with every `path:line` that imports a named export, or a namespace;
+- **not used here** — nothing imported matches;
+- **behavioural — check by hand** — with the files that import the entrypoint;
+- **not declared — check by hand** — an item from before the line existed, with the files that
+  import the entrypoints it leads with.
+
+`--json` prints the same verdicts per item for a CI step. The scan reads static `import` and
+`export … from` declarations, bare imports and `import()` / `require()` of a literal specifier; a
+specifier built at run time is invisible to it, and so is a file of another kind (`.astro`,
+`.mdx`). A directory or file the process may not read is
+listed under **Not scanned** (`unscanned` in `--json`) instead of ending the plan: the verdicts do
+not cover it.
+
 ## Released migration: 0.88.0
 
 Two mechanical edits, and only if your project builds these values rather than only reading them.
@@ -20358,8 +20575,11 @@ The browser-and-server entrypoint. Re-exports everything from
 | `LiveStateSource` / `LiveStateSourceOpenInput` / `LiveStateSourceOpenResult` | _types_ | host binding for one continuous snapshot/event boundary; transport retry and cursor semantics remain host-owned |
 | `LiveStateControllerError` / `LiveStateSubscriberError` | _types_ | isolated observer failure payloads that do not change source or subscriber truth |
 | `createRetainedTopics` | function | retained last-value store for sticky events — [guide](../guide/realtime.md#sticky-events) |
-| `parseSSE` | function | parse an SSE `Response` into an async generator — [guide](../guide/client.md#sse) |
-| `parseNDJSON` | function | parse bounded fatal-UTF-8 NDJSON; blank keep-alives are skipped and `finalLine: 'require-newline'` can make the delimiter mandatory — [guide](../guide/client.md#ndjson) |
+| `parseSSE` | function | parse SSE from a `Response`, a web stream or an async byte iterable into an async generator — [guide](../guide/client.md#sse) |
+| `parseNDJSON` | function | parse bounded fatal-UTF-8 NDJSON from a `Response`, a `ReadableStream<Uint8Array>` or an `AsyncIterable<Uint8Array>` (a child's stdout); blank keep-alives are skipped, `finalLine: 'require-newline'` makes the delimiter mandatory and `signal` cancels the source — [guide](../guide/client.md#any-byte-source) |
+| `createNDJSONDecoder` / `NDJSONDecoder` | function / _type_ | the same bounded NDJSON reading driven by `push(chunk)` / `end()`, for a socket `data` callback |
+| `StreamByteSource` | _type_ | `Response \| ReadableStream<Uint8Array> \| AsyncIterable<Uint8Array>`, what the NDJSON and SSE readers accept |
+| `StreamLineLimitError` / `StreamTruncatedLineError` | class | a line past `maxLineBytes` (`limitBytes`, `lineBytes`; a `RangeError`) and a source ended inside a line under `require-newline` (`lineBytes`; a `SyntaxError`) |
 | `resumableIterator` | function | re-open a long-lived stream from the last delivered cursor, with jittered backoff, a caller-owned terminal item and prompt abort — [guide](../guide/client.md#resumable-streams) |
 | `createBackoff` | function | exponential backoff with subtractive jitter as a value: `next()` / `reset()` |
 | `ContractStreamFrameSchema` / `ContractStreamFrame` | schema / _type_ | default on-the-wire `data` / safe `error` / `end` envelope of a contract-first stream |
@@ -22173,6 +22393,9 @@ handler pipeline without opening a TCP port.
 |--------|------|---------|
 | `createHandlerTestClient` | function | one contract client backed by an in-process `FetchHandler` |
 | `createHandlerTestClients` | function | exact contract-registry batch form |
+| `createManualClock` / `ManualClock` | function / _type_ | manual time for schedules, retries and deadlines: `now`, `wallNow`, `schedule`, `advance(ms)` firing due timers in order with real event-loop yields between them, `until`, `pending` and `hold`; a `ManagedScheduleClock`, `DurabilityClock`, `RevisionSignalClock` and `BoundedAdmissionClock` — [guide](../guide/testing-and-deployment.md#manual-time-for-schedules-and-retries) |
+| `ManualClockOptions` / `ManualClockUntilOptions` / `ManualClockTimer` / `ManualClockHold` | _types_ | start and wall instants, event-loop turns per firing and the real-time hold limit; `until` step and manual limit; a cancellable timer; a hold that is released or parked |
+| `ManualClockError` / `ManualClockErrorCode` | class / _type_ | `MANUAL_CLOCK_HOLD_TIMEOUT` naming the open holds, or `MANUAL_CLOCK_LIMIT` when `until` runs out |
 | `runManagedResourceConformance` | function | run the canonical deterministic lifecycle matrix against a fresh consumer-owned `ManagedResource` fixture; resolves `void` or throws `ManagedResourceConformanceError` with a stable scenario ID and normalized trace |
 | `ManagedResourceConformanceScenarioIdSchema` / `ManagedResourceConformanceScenarioId` | schema / _type_ | stable clean, rollback, readiness/completion, activation, shutdown-race and forced-cleanup scenario vocabulary |
 | `ManagedResourceConformanceScenarioSchema` / `ManagedResourceConformanceScenario` | schema / _type_ | discriminated scenario record including whether the controlled resource is required |
@@ -22282,7 +22505,10 @@ injected grammY bot. → ADR 0143, ADR 0201 — [guide](../guide/telegram.md)
 | `TelegramInitDataRefusal` | _type_ | `missing-hash` / `signature-mismatch` / `malformed` / `expired` — an expired string is not a forged one |
 | `classifyTelegramSendFailure` | function | name a refused Bot API send and separate "retry this send" from "stop addressing this recipient" |
 | `TelegramSendFailure` | _type_ | reason, `status`, Telegram-stated `retryAfterSeconds`, `retryable`, `recipientUnreachable` and which evidence produced the answer |
-| `TelegramSendFailureReason` / `TELEGRAM_SEND_FAILURE_REASONS` | _type_ / constant | `blocked-by-user` / `user-deactivated` / `chat-not-found` / `not-started` / `rate-limited` / `message-invalid` / `server-error` / `unknown`, and the same as a list; a `Record<TelegramSendFailureReason, …>` over them fails to compile when a reason is added |
+| `createTelegramBotTransport` / `TelegramBotTransportOptions` | function / _type_ | a `fetch` for the Bot API senders that connects before it writes, so a failure before the first byte is `TelegramNotDispatchedError`; connection attempt and budget, answer timeout and size, injectable resolver and socket factory — [guide](../guide/telegram.md#a-transport-that-knows-whether-a-request-left) |
+| `TelegramFetch` / `TelegramBotTransportOpen` / `TelegramBotTransportResolve` / `TelegramBotTransportSocket` | _types_ | the `(url, init) => Promise<Response>` the senders take; the transport's socket factory, resolver and the structural socket it needs (a Node `net.Socket` or `tls.TLSSocket` fits) |
+| `TelegramNotDispatchedError` / `TelegramNotDispatchedStage` | class / _type_ | a request that provably never left (`lookup`, `connect` or `request`), so repeating it cannot duplicate a message |
+| `TelegramSendFailureReason` / `TELEGRAM_SEND_FAILURE_REASONS` | _type_ / constant | `blocked-by-user` / `user-deactivated` / `chat-not-found` / `not-started` / `rate-limited` / `message-invalid` / `server-error` / `not-dispatched` / `unknown`, and the same as a list; a `Record<TelegramSendFailureReason, …>` over them fails to compile when a reason is added |
 | `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 |
@@ -22833,7 +23059,10 @@ Native POSIX Bun/Node one-shot command execution. See [native IO](../guide/nativ
 `stitchkit/files/packaging` owns `createNativePackaging` and the types
 `NativePackagingOptions`, `NativePackagingAsset`, `NativePackagingPlugin`, `NativePackagingResult`,
 and for a standalone executable `NativePackagingEmbeddedOptions`, `NativePackagingEmbeddedAsset`,
-`NativePackagingEmbeddedResult`.
+`NativePackagingEmbeddedResult`. `inspectNativeArtifact` classifies a built artifact's bytes by the
+loader it carries as a `NativeArtifactLoader`: `packaged`, `unpackaged` or `no-loader`. The plugin
+fails a build whose entry imports the default loader of another `stitchkit` installation, naming
+both versions and roots.
 It resolves the installed package's target/version, reads each selected addon once and checks it
 against the `size` and `sha256` published in the package's `native-assets.json` (`formatVersion: 2`,
 written when Stitchkit is built). Call it once per build and reuse the result.

package/llms.txt

@@ -9,7 +9,7 @@ Build with stitchkit: define a contract once, then `implement` it and serve it (
 Load the slice for each entrypoint your code imports — `import … from 'stitchkit/server'` → `llms/server.txt`; the root `stitchkit` import → `llms/stitchkit.txt`. A slice holds that entrypoint's API reference section and the guide pages whose home it is; every guide lives in exactly one slice, and a slice that needs another's guide names it under "Also read". Each file is at most 50.0 KB; a longer one continues in numbered parts, each naming the next at its top. Moving across versions: load `llms/upgrading.txt` and the range slices it lists between your version and the target. `llms-full.txt` inlines everything; it is far larger than a context window, so do not read it whole.
 
 ## Entrypoint slices
-- **stitchkit**: [llms/stitchkit.txt](llms/stitchkit.txt) 17.6 KB → [llms/stitchkit.2.txt](llms/stitchkit.2.txt) 46.2 KB → [llms/stitchkit.3.txt](llms/stitchkit.3.txt) 17.1 KB
+- **stitchkit**: [llms/stitchkit.txt](llms/stitchkit.txt) 46.5 KB → [llms/stitchkit.2.txt](llms/stitchkit.2.txt) 36.5 KB
 - **stitchkit/live**: [llms/live.txt](llms/live.txt) 21.2 KB
 - **stitchkit/react**: [llms/react.txt](llms/react.txt) 8.6 KB
 - **stitchkit/react/keyboard**: [llms/react-keyboard.txt](llms/react-keyboard.txt) 9.2 KB
@@ -39,10 +39,10 @@ Load the slice for each entrypoint your code imports — `import … from 'stitc
 - **stitchkit/application/directory-inbox**: [llms/application-directory-inbox.txt](llms/application-directory-inbox.txt) 0.3 KB
 - **stitchkit/application/diagnostic-journal**: [llms/application-diagnostic-journal.txt](llms/application-diagnostic-journal.txt) 1.8 KB
 - **stitchkit/application/schemas**: [llms/application-schemas.txt](llms/application-schemas.txt) 1.8 KB
-- **stitchkit/testing**: [llms/testing.txt](llms/testing.txt) 30.7 KB
+- **stitchkit/testing**: [llms/testing.txt](llms/testing.txt) 33.6 KB
 - **stitchkit/agent-runtime/sandbox**: [llms/agent-runtime-sandbox.txt](llms/agent-runtime-sandbox.txt) 8.3 KB
 - **stitchkit/files**: [llms/files.txt](llms/files.txt) 5.5 KB
-- **stitchkit/telegram**: [llms/telegram.txt](llms/telegram.txt) 30.1 KB
+- **stitchkit/telegram**: [llms/telegram.txt](llms/telegram.txt) 32.9 KB
 - **stitchkit/telegram/html**: [llms/telegram-html.txt](llms/telegram-html.txt) 2.7 KB
 - **stitchkit/telegram/screens**: [llms/telegram-screens.txt](llms/telegram-screens.txt) 21.2 KB
 - **stitchkit/tracking**: [llms/tracking.txt](llms/tracking.txt) 16.8 KB
@@ -56,13 +56,13 @@ Load the slice for each entrypoint your code imports — `import … from 'stitc
 - **stitchkit/node**: [llms/node.txt](llms/node.txt) 3.1 KB
 - **stitchkit/agent-runtime/react**: [llms/agent-runtime-react.txt](llms/agent-runtime-react.txt) 1.0 KB
 - **stitchkit/agent-runtime/realtime**: [llms/agent-runtime-realtime.txt](llms/agent-runtime-realtime.txt) 2.6 KB
-- **stitchkit/process**: [llms/process.txt](llms/process.txt) 42.5 KB
-- **stitchkit/files/packaging**: [llms/files-packaging.txt](llms/files-packaging.txt) 3.2 KB
+- **stitchkit/process**: [llms/process.txt](llms/process.txt) 43.3 KB
+- **stitchkit/files/packaging**: [llms/files-packaging.txt](llms/files-packaging.txt) 3.5 KB
 
 ## Upgrading slices
-- **Upgrading — how to move across versions**: [llms/upgrading.txt](llms/upgrading.txt) 10.3 KB
-- **Upgrading 0.98.0 → 0.107.0**: [llms/upgrading-0.98.0-0.107.0.txt](llms/upgrading-0.98.0-0.107.0.txt) 45.9 KB
-- **Upgrading 0.72.0 → 0.97.0**: [llms/upgrading-0.72.0-0.97.0.txt](llms/upgrading-0.72.0-0.97.0.txt) 43.8 KB
+- **Upgrading — how to move across versions**: [llms/upgrading.txt](llms/upgrading.txt) 12.1 KB
+- **Upgrading 0.100.0 → 0.108.0**: [llms/upgrading-0.100.0-0.108.0.txt](llms/upgrading-0.100.0-0.108.0.txt) 46.1 KB
+- **Upgrading 0.72.0 → 0.99.0**: [llms/upgrading-0.72.0-0.99.0.txt](llms/upgrading-0.72.0-0.99.0.txt) 46.4 KB
 - **Upgrading 0.59.0 → 0.71.0**: [llms/upgrading-0.59.0-0.71.0.txt](llms/upgrading-0.59.0-0.71.0.txt) 45.6 KB
 - **Upgrading 0.37.0 → 0.58.0**: [llms/upgrading-0.37.0-0.58.0.txt](llms/upgrading-0.37.0-0.58.0.txt) 40.0 KB
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "stitchkit",
-  "version": "0.107.0",
+  "version": "0.108.1",
   "description": "Contract-first backend framework — one defineContract() into an HTTP API, MCP tools, AI-agent tools and a typed client. Bun and Node.",
   "keywords": [
     "bun",

package/llms/stitchkit.3.txt

@@ -1,177 +0,0 @@
-# stitchkit — stitchkit docs slice, part 3 of 3
-
-> Generated from the `docs/` tree by `bun run gen:llms`. The index of all slices is
-> `llms.txt` in this package.
-
-Parts of this slice:
-- `llms/stitchkit.txt`: Guide: Getting started  (docs/guide/getting-started.md)
-- `llms/stitchkit.2.txt`: Guide: Typed client  (docs/guide/client.md)
-- `llms/stitchkit.3.txt`: API reference: `stitchkit`  (docs/api/reference.md)
-
-Also read:
-- see `llms/contract.txt` for the Contracts guide
-- see `llms/server.txt` for the Realtime guide
-- see `llms/server.txt` for the Auth & errors guide
-
-==============================================================================
-# API reference: `stitchkit`  (docs/api/reference.md)
-==============================================================================
-
-## `stitchkit`
-
-The browser-and-server entrypoint. Re-exports everything from
-[`stitchkit/contract`](#stitchkitcontract), plus the client and browser realtime.
-
-### Client
-
-| Export | Kind | Summary |
-|--------|------|---------|
-| `createClient` | function | build a typed client from a contract — [guide](../guide/client.md#createclient) |
-| `createClients` | function | build one exact typed client per contract from a registry; accepts the same scoped config and transports as `createClient` |
-| `createScopedClients` | function | build one registry routed by contract scope; arrays compose contracts into one namespace |
-| `createScopedUrlBuilders` | function | build one URL registry routed by contract scope; arrays compose contracts into one namespace |
-| `ScopeClientConfigs` | _type_ | per-scope routing configuration consumed by scoped clients and URL builders |
-| `ScopedClientRegistry` | _type_ | exact composed registry returned by `createScopedClients` |
-| `ScopedUrlBuilderRegistry` | _type_ | exact composed registry returned by `createScopedUrlBuilders` |
-| `ClientRegistryValue` | _type_ | one contract or a contract array composing one client namespace |
-| `ClientContract` | _type_ | HTTP-client-compatible contract value used by scoped registries |
-| `RegistryScope` | _type_ | contract-scope union inferred from a scoped client registry value |
-| `createUrlBuilder` | function | build synchronous browser-native URLs for all HTTP endpoints; body methods accept URL-bound args only — [guide](../guide/client.md#contract-url-builders) |
-| `createUrlBuilders` | function | build one exact URL builder per contract in a registry |
-| `UrlBuilderConfig` | _type_ | explicit `{ baseUrl }` source for a URL builder |
-| `ClientConfig` | _type_ | config for `createClient`'s bare-fetch mode (2nd arg, no `HttpClient`) |
-| `ClientFetch` | _type_ | injectable Fetch-compatible transport used by framework and application-owned adapters |
-| `ClientRequestOptions` | _type_ | per-call `{ signal?, onUploadProgress? }` passed through an endpoint callable's `.withOptions(...)`; caller abort is distinct from timeout — [guide](../guide/client.md#per-call-cancellation) |
-| `UploadProgress` | _type_ | `{ sentBytes, totalBytes, attempt }` heard by `onUploadProgress`: bytes of the encoded body handed to the network, first `0`, last `totalBytes`, counted again on each transport retry — [guide](../guide/client.md#upload-progress) |
-| `uploadInChunks` | function | send a file larger than one request as `init` → parts → `finalize` through three calls the app owns; client-minted id, repeats of a part on a failure that may pass, `finalize` never repeated, cancel checked between parts, progress in file bytes — [guide](../guide/client.md#chunked-uploads) |
-| `ChunkedUploadConfig` / `ChunkedUploadStart` / `ChunkedUploadPart` / `ChunkedUploadProgress` | _type_ | the driver's file, part size, retries and three calls; what `init` declares; one part; progress `{ sentBytes, totalBytes, index, chunkCount, attempt }` |
-| `ChunkSource` | _type_ | what the driver reads a file through — `size` and `slice(start, end)`; a `Blob` is one, so is a platform file that is not (an Expo `File`), and a part's `bytes` is what its `slice` returns |
-| `ContractClientConfig` | _type_ | per-tenant / resource-scoped client config — dynamic `pathPrefix` + `stripPrefixKeys` ([guide](../guide/client.md#contractclientconfig--per-tenant--resource-scoped-clients)) |
-| `contractEndpointMatchers` | function | compile exact pathname matchers for selected HTTP contract operations and expected-401 policy |
-| `PathPrefixArgs` | _type_ | required string-valued keys exposed to a typed dynamic `pathPrefix` callback |
-| `createHttpClient` | function | the Ky-based HTTP transport; on Next.js SSR its first attempt stays request-memoizable while every retry is a distinct transport attempt — [guide](../guide/client.md#createhttpclient) |
-| `ApiError` | class | a non-2xx or client failure, with `code` / `status` / `details` / `hint`, optional readonly `traceId` from `x-request-id`, and standard `cause` preserving an injected transport failure |
-| `zodIssues` | function | a `ZodError` → structured `{ path, code, message }[]` — the exact projection a `VALIDATION_ERROR` carries in `ApiError.details.issues`, so a caller renders one shape. Also on `stitchkit/server`; same name, one definition |
-| `ZodIssueSummary` | _type_ | one structured validation issue (`{ path, code, message }`) — the element type of `details.issues`. Also on `stitchkit/server` |
-| `formatZodError` | function | a `ZodError` → a readable, field-summarised string. Also on `stitchkit/server` |
-| `HttpClient` | _type_ | the transport interface `createClient` builds on |
-| `ConfiguredHttpClient` | _type_ | a framework-created `HttpClient` carrying its readonly `baseUrl` for URL builders |
-| `HttpClientConfig` | _type_ | config for `createHttpClient`; retry `limit` counts retries after the initial attempt (default 2 = at most 3 GET attempts), with `statusCodes: []` by default; `fetch` installs an explicit transport and is mutually exclusive with the legacy Bun-only `unix` option — [details](../guide/client.md#createhttpclient) |
-| `UnauthorizedMatcher` | _type_ | exact `(pathname) => boolean` policy accepted by `suppressUnauthorizedFor` |
-| `RequestOptions` | _type_ | per-call options — params, timeout, response type, `onUploadProgress` |
-| `HeaderProvider` | _type_ | static or per-request headers |
-| `ApiEvent` | _type_ | a client event — `unauthorized` / `network_error` / `logout` |
-| `ApiEventListener` | _type_ | an `ApiEvent` handler |
-
-### Realtime (client) & streaming
-
-| Export | Kind | Summary |
-|--------|------|---------|
-| `createSocketIOClient` | function | low-level typed Socket.IO transport primitive — [guide](../guide/realtime.md#low-level-transport) |
-| `defineRealtimeContract` | function | Zod-first shared Socket.IO event contract — [guide](../guide/realtime.md#zod-first-event-contract) |
-| `createRealtimeClient` | function | inferred, runtime-validated Socket.IO client — [guide](../guide/realtime.md#client--createrealtimeclient) |
-| `bindRealtimeClient` | function | bind contract validation and typed acknowledgements to an existing Stitchkit client transport without owning its lifecycle |
-| `createLiveStateController` | function | keep typed application state current across one source-owned snapshot/event generation with finite pre-snapshot buffering, generation fencing and explicit resync — [guide](../guide/realtime.md#snapshot--event-state-synchronization) |
-| `LiveStateController` | _type_ | renderer-neutral `start` / `resync` / `getSnapshot` / `subscribe` / `close` handle |
-| `LiveStateControllerConfig` | _type_ | typed source, reducer, explicit event/byte bounds, event sizing and isolated error hooks |
-| `LiveStateControllerSnapshot` / `LiveStateControllerStatus` | _types_ | current value plus phase, generation, buffer and application/duplicate/gap/refusal counters |
-| `LiveStateControllerStatusSchema` | schema | strict runtime validation for controller status metadata |
-| `LiveStatePhaseSchema` / `LiveStatePhase` | schema / _type_ | `idle`, `opening`, `live`, `resync-required`, `unavailable` or `closed` |
-| `LiveStateStopReasonSchema` / `LiveStateStopReason` | schema / _type_ | explicit gap, overflow, source loss, controller failure and bounded `controller-capacity` reasons |
-| `LiveStateEventDecision` | _type_ | provider-owned reducer result: applied state, duplicate or gap |
-| `LiveStateSource` / `LiveStateSourceOpenInput` / `LiveStateSourceOpenResult` | _types_ | host binding for one continuous snapshot/event boundary; transport retry and cursor semantics remain host-owned |
-| `LiveStateControllerError` / `LiveStateSubscriberError` | _types_ | isolated observer failure payloads that do not change source or subscriber truth |
-| `createRetainedTopics` | function | retained last-value store for sticky events — [guide](../guide/realtime.md#sticky-events) |
-| `parseSSE` | function | parse an SSE `Response` into an async generator — [guide](../guide/client.md#sse) |
-| `parseNDJSON` | function | parse bounded fatal-UTF-8 NDJSON; blank keep-alives are skipped and `finalLine: 'require-newline'` can make the delimiter mandatory — [guide](../guide/client.md#ndjson) |
-| `resumableIterator` | function | re-open a long-lived stream from the last delivered cursor, with jittered backoff, a caller-owned terminal item and prompt abort — [guide](../guide/client.md#resumable-streams) |
-| `createBackoff` | function | exponential backoff with subtractive jitter as a value: `next()` / `reset()` |
-| `ContractStreamFrameSchema` / `ContractStreamFrame` | schema / _type_ | default on-the-wire `data` / safe `error` / `end` envelope of a contract-first stream |
-| `ContractStreamFraming` / `ContractStreamCompletion` | _types_ | opt-in item-vs-envelope framing and terminal-vs-stream-end completion policies |
-| `StreamFinalLinePolicy` | _type_ | permissive or newline-required final NDJSON line policy |
-| `DEFAULT_CONTRACT_STREAM_FRAME_BYTES` | const | default maximum encoded contract-stream frame: 256 KiB |
-| `SocketIOClient` | _type_ | low-level client handle; `emit` reports disconnected drops and `emitWithAck` exposes the native Promise primitive used by validated `request()` |
-| `SocketIOClientPeerLoaders` | _type_ | inject `socket.io-client` so a bundler can put it in a self-contained artifact |
-| `SocketIOClientConfig` | _type_ | config for `createSocketIOClient` (incl. `retain`, `onConnectError`, `onDroppedEmit`) |
-| `SocketEventMap` | _type_ | the shape of an event map |
-| `RealtimeClient` | _type_ | validated client inferred from a realtime contract |
-| `RealtimeClientOptions` | _type_ | transport options plus rejected-event and metadata-only acknowledged-request phase hooks for `createRealtimeClient` |
-| `BoundRealtimeClient` | _type_ | validated non-owning `on`/`emit`/`request` client with no `connect`/`disconnect` |
-| `RealtimeClientTransport` | _type_ | minimal existing transport capability accepted by `bindRealtimeClient` |
-| `BindRealtimeClientOptions` | _type_ | rejection/logger options for a bound existing transport |
-| `RealtimeAcknowledgedEvent` | _type_ | event-name union restricted to definitions with an `ack` schema |
-| `RealtimeAcknowledgement` | _type_ | validated acknowledgement output inferred from an event definition |
-| `RealtimeRequestArguments` | _type_ | request arguments inferred from an acknowledged event tuple |
-| `RealtimeRequestOptions` | _type_ | finite positive native acknowledgement `timeoutMs` plus an optional invocation-scoped `onPhase` observer |
-| `RealtimeRequestPhaseSchema` / `RealtimeRequestPhase` | schema / _type_ | closed `engine-handoff` / `engine-ack-received` / `settled` / `timeout` / `disconnected` lifecycle |
-| `RealtimeRequestPhaseEventSchema` / `RealtimeRequestPhaseEvent` | schema / _type_ | strict metadata-only `{ requestId, event, phase, elapsedMs }` observation |
-| `RealtimeRequestPhaseHook` | _type_ | isolated sync/async observer accepted globally by `RealtimeClientOptions.onRequestPhase` or per invocation by `RealtimeRequestOptions.onPhase` |
-| `RealtimeRequestTimeoutError` | class | stable `REALTIME_REQUEST_TIMEOUT` rejection |
-| `RealtimeRequestDisconnectedError` | class | stable `REALTIME_REQUEST_DISCONNECTED` rejection, including an immediate disconnected call |
-| `RealtimeRequestInvalidAcknowledgementError` | class | invalid ack was reported through `onRejected` and the request rejected |
-| `RealtimeRequestRejectedError` | class | the peer refused the frame against its own contract and said so — `reason`, `issues` — instead of leaving the sender to time out ([ADR 0106](../decisions/0106-a-refused-frame-answers-its-sender.md)) |
-| `REALTIME_REJECTION_KEY` | const | the reserved acknowledgement key a refusal travels under |
-| `RealtimeRejectionEnvelope` | _type_ | the wire shape of a refusal |
-| `RealtimeRejectionReport` | _type_ | what the sender is told: event, reason, message, issues |
-| `RealtimeRejectionIssue` | _type_ | one refused field, already flattened (`path: '0.v'`) |
-| `asRealtimeRejection` | function | recognise a refusal in an acknowledgement value, validating it |
-| `RealtimeContract` | _type_ | shared server-to-client and client-to-server event registries |
-| `RealtimeEventRegistry` | _type_ | string-keyed registry of event definitions |
-| `RealtimeEventDefinition` | _type_ | one tuple-shaped event and optional acknowledgement schema |
-| `RealtimeEventArguments` | _type_ | tuple inferred from an event definition |
-| `RealtimeEmitArguments` | _type_ | emit arguments including an inferred acknowledgement callback |
-| `RealtimeEventHandler` | _type_ | handler inferred from an event definition |
-| `InferRealtimeEventMap` | _type_ | inferred Socket.IO-compatible event map |
-| `RealtimeRejectDirection` / `RealtimeRejectPhase` / `RealtimeRejectReason` / `RealtimeRejectFault` | _types_ | canonical inferred rejection direction, validation phase, reason and fault classification |
-| `RealtimeRejectedEvent` | _type_ | structured rejected event with event, direction, phase, reason and fault |
-| `RealtimeRejectedEventHook` | _type_ | sync/async observer for structured realtime rejections |
-| `ValidatedRealtimeSocket` | _type_ | runtime-validating `on`/`emit` surface inferred from registries; `emit` returns "accepted by the transport" (`false` only for a client-side disconnected drop) |
-| `RetainedTopics` | _type_ | the `createRetainedTopics` handle |
-| `ParseSSEOptions` | _type_ | options for `parseSSE` |
-| `ParseNDJSONOptions` | _type_ | options for `parseNDJSON` |
-| `BackoffPolicySchema` / `BackoffPolicy` | schema / _type_ | `minDelayMs`, `maxDelayMs` and a `0`–`1` jitter fraction; a ceiling below the floor is refused |
-| `Backoff` | _type_ | the backoff handle returned by `createBackoff` |
-| `ResumableIteratorConfig` | _type_ | caller-owned `open` / `advance` / `isTerminal`, retry policy, abort signal and `onAttempt` observer |
-| `ResumableAttempt` | _type_ | attempt number, the delay about to be waited and the error that caused it |
-
-### Trace (client)
-
-Browser-safe W3C trace helpers — the same functions as on
-[`stitchkit/observability`](#stitchkitobservability), re-exported so a client
-can emit / propagate a `traceparent` (see `HttpClientConfig.trace`).
-
-| Export | Kind | Summary |
-|--------|------|---------|
-| `createTraceContext` | function | a fresh root trace |
-| `formatTraceparent` | function | render a `traceparent` header value |
-| `parseTraceparent` | function | parse a `traceparent` header |
-| `childSpan` | function | a child span of a parent trace |
-| `TraceContext` | _type_ | `{ traceId, spanId, parentSpanId?, tracestate?, baggage? }` |
-
----
-
-### Session lifetime and credential coordination
-
-`createSessionScope` (`stitchkit`) returns the generic `SessionScope`: `replace(context)`
-creates a new login lifetime (including same-account relogin), `capture()` returns
-its `SessionOperation<T>`, `clear()` invalidates it, `stop()` permanently closes
-the host, and `owns(operation)` answers whether an operation is this scope's current
-one — `current()` alone cannot tell an operation of another scope. Operations expose `id`, `generation`, `context`, `signal`, `current()` and
-`assertCurrent()`. `run(callback)` checks both success and failure across an await;
-`deliver(callback)` admits a synchronous final send/state change or returns false.
-`bindFetch(fetch, headers?)` guards every attempt and scopes its abort signal. Wrap
-the complete client call in `run` too: headers are not the response body boundary.
-Expired work throws `SessionExpiredError`, not a refresh instruction; when the work
-itself failed, that failure is its `cause`.
-
-`createSessionCredentials` accepts `SessionCredentialsConfig`:
-`scope`, `refresh(credentials, signal)`, `storage.write(session, credentials)`,
-`storage.clear()`, `maxPendingWrites` (128), `refreshTimeoutMs` (30000, at most one
-hour) and `storageTimeoutMs` (30000, at most one hour): a storage call past it
-rejects and frees the queue, so `logout()` still clears; when the late call settles,
-storage is written again from memory, or cleared when nobody is logged in. `SessionCredentials` provides `login`, `logout`, `read(operation)` and
-`refresh(operation)`. Concurrent refresh calls in one generation share the same
-promise. Logout invalidates memory before its returned persistence promise settles.
-Storage errors and queue-capacity refusals reject; callers must handle them. All
-writes must pass through the same instance. There is no cross-process/tab lock,
-provider error classifier or automatic retry of arbitrary application callbacks.