stitchkit 0.106.1 → 0.108.0

package/llms/upgrading.txt

@@ -11,10 +11,10 @@ Contains: Guide: Upgrading, general  (docs/guide/upgrading.md)
 
 Load this slice, then every range slice between your installed version and the target:
 
-- 0.96.0 → 0.106.0: `llms/upgrading-0.96.0-0.106.0.txt`
-- 0.69.0 → 0.95.0: `llms/upgrading-0.69.0-0.95.0.txt`
-- 0.55.0 → 0.68.0: `llms/upgrading-0.55.0-0.68.0.txt`
-- 0.37.0 → 0.53.0: `llms/upgrading-0.37.0-0.53.0.txt`
+- 0.100.0 → 0.108.0: `llms/upgrading-0.100.0-0.108.0.txt`
+- 0.72.0 → 0.99.0: `llms/upgrading-0.72.0-0.99.0.txt`
+- 0.59.0 → 0.71.0: `llms/upgrading-0.59.0-0.71.0.txt`
+- 0.37.0 → 0.58.0: `llms/upgrading-0.37.0-0.58.0.txt`
 
 # Upgrading stitchkit
 
@@ -41,6 +41,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.
+
 ## What your range does, and does not, do for you
 
 A caret range (`"stitchkit": "^0.71.0"`) is a real gate: it resolves `< 0.72.0`,

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 51 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 51 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 51 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:
@@ -8585,23 +8626,55 @@ version: carry their reachable relative `.d.ts` closure, rather than emitting re
 instead emit declarations for only that DTO contract. Keep the library's manifest at runtime
 `dependencies: {}` and `peerDependencies: { zod: ... }` when that is its declared promise.
 
-The packaged Darwin loader names its addons by a path computed at run time, so a bundler
-never follows it: bundling `stitchkit/server`, `stitchkit/files` or `stitchkit/process` yields
-the same single JS file on every operating system, with no `.node` output, and
-`bun build --outfile` works. Such a bundle looks for the addon beside the original package
-files, never inside itself. Where that file is absent (an artifact moved to another machine)
-the Darwin backend is `unavailable`: process identity cannot be recorded, so a lock held by a
-crashed owner is not reclaimed. An artifact that must carry the Darwin addon uses the packaging
-plugin of the next section; it is the only way a static loader enters a bundle.
+The packaged Darwin loader computes its addon path at run time from its own file
+(`module.filename`), so a bundler never follows it: bundling `stitchkit/server`,
+`stitchkit/files` or `stitchkit/process` yields the same single JS file on every operating
+system, with no `.node` output, `bun build --outfile` works, and no path of the build machine
+becomes a literal of the artifact. A bundle has no installed package beside it, so without the
+packaging plugin it never loads the addon: the first call that needs it reports the Darwin backend
+`unavailable` with stage `packaging`, and the message names `createNativePackaging`. An artifact
+that must carry the Darwin addon uses the packaging plugin of the next section; it is the only way
+a static loader enters a bundle.
+
+Only these calls load the addon, and only on macOS: process identity (`observeProcessInstance`
+and `probeProcessOwner`), every exclusive lock (`withExclusiveLock` and what is built on it, such
+as the file state store and the diagnostic journal) and the contained file operations of the Agent
+coding tools. Without the addon a lock still works, but it cannot record or check its owner's
+identity, so a lock held by a crashed owner is not reclaimed. The managed file boundary
+(`createManagedFileBoundary` and the transfer tools built on it), atomic writes and the chunk
+spool never load it, on any operating system. The package is free of import side effects
+(`sideEffects: false`), so a bundle that imports only those parts carries no Darwin loader at all.
+
+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.
+`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
 ```
 
+That plain build serves Linux and the parts that never load the addon. A library whose consumers
+take locks or read process identity on macOS builds each native entry with the companion plugin of
+the next section (one entry per build, `naming.entry` equal to `entryPath`) and ships the addon it
+writes beside the entries.
+
 Qualify the complete output outside its build tree and installed dependency graph. Test process
 identity, live-owner refusal, dead-owner recovery and contained file operations in artifacts built
 with the packaging plugin, and check that an unpackaged build reports the backend `unavailable`
-rather than certifying a dead owner. Bun and Node package imports retain the same
+with stage `packaging` rather than certifying a dead owner. Bun and Node package imports retain the same
 lazy loader; importing a portable leaf does not load a Darwin addon on another OS. Test
 declarations too, and check that importing an unbundled Stitchkit leaf fails in a deliberately
 isolated library distribution. A separate schema-only entry must not import the native entry.
@@ -8609,7 +8682,9 @@ isolated library distribution. A separate schema-only entry must not import the
 If the Darwin backend cannot load, `observeProcessInstance` still returns `unavailable`.
 Its backend `Error` preserves the original `cause`; JSON serialization carries only the stable
 `DARWIN_BACKEND_UNAVAILABLE` code, architecture, safe message and failure stage
-(`architecture`, `resolve`, `load` or `surface`), plus a recognized native error code when present.
+(`architecture`, `packaging`, `resolve`, `load` or `surface`), plus a recognized native error code
+when present: `packaging` is a bundle built without the packaging plugin, with native code
+`STITCHKIT_NATIVE_NOT_PACKAGED`.
 It excludes stack, paths and nested cause. This backend diagnosis does not reclassify kernel
 failures or turn unavailable identity into proof that an owner is dead. If a runtime provides
 no recognized native error code, the stage stays `load`; the loader never infers errno from text.
@@ -8656,7 +8731,7 @@ for (const asset of native.assets) {
 }
 ```
 
-`entryPath` and `assetPath` are relative paths inside the application's output root, without
+In companion delivery, `entryPath` and `assetPath` are relative paths inside the application's output root, without
 absolute paths, traversal or overlapping file/directory paths. `assetPath` may contain `[hash]`,
 which becomes the first 16 hex digits of that addon's published SHA256: the digest is known before
 the build, so `addons/darwin-arm64-[hash].node` gives two installed versions of the package
@@ -8665,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
@@ -8695,10 +8775,27 @@ process primitives without loading Darwin assets. Qualify the exact same JS byte
 Darwin arm64 and x64 machines, with both companions preserved through archive delivery.
 Build-machine architecture and cross-build success cannot establish universal native support.
 
-For a standalone executable use `delivery: 'embedded'` and the same plugin in `Bun.build`
-with `compile: { outfile: ... }`. Bun embeds the selected addon from the verified bytes the
-plugin holds, not from a second read of the file; `assets` identifies those bytes and their
-published digest for qualification, not a companion that must be installed beside the executable.
+For a standalone executable use `delivery: 'embedded'` and its plugin in `Bun.build` with
+`compile`. An executable carries the addon inside itself, so this form names no `entryPath` or
+`assetPath`; passing one is a type error and a schema refusal, never silently ignored:
+
+```ts
+const native = createNativePackaging({
+  platform: 'darwin', architecture: 'arm64', delivery: 'embedded',
+})
+if (native.state !== 'ready') throw new Error(native.code)
+const result = await Bun.build({
+  entrypoints: ['src/cli.ts'], minify: true,
+  compile: { target: 'bun-darwin-arm64', outfile: 'dist/cli' },
+  plugins: [native.plugin],
+})
+if (!result.success) throw new AggregateError(result.logs, 'Build failed')
+```
+
+Bun embeds the selected addon from the verified bytes the plugin holds, not from a second read of
+the file, and the executable loads it from `/$bunfs/root/darwin-arm64-<hash>.node`. Its `assets`
+(`NativePackagingEmbeddedAsset`: `bytes`, `size`, `sha256`) identify those bytes and their
+published digest for qualification; there is nothing to write beside the executable.
 Cross-builds must select the requested architecture explicitly; the artifact must run on that target.
 The installed package must contain that target's addon. No automatic fallback/downgrade occurs.
 
@@ -13880,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
@@ -14973,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
@@ -14993,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
@@ -15580,6 +15751,94 @@ 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
+
+**Who must act:** builds that call `createNativePackaging` (`stitchkit/files/packaging`) with
+`delivery: 'embedded'`. Companion delivery is unchanged.
+
+A standalone executable carries the Darwin addon inside itself, so the embedded form takes only
+`platform`, `architecture` and `delivery`. `entryPath` and `assetPath` were required before but
+changed nothing in the executable; passing them now is a type error and a schema refusal. The
+ready result names the embedded addon by `NativePackagingEmbeddedAsset` (`bytes`, `size`,
+`sha256`), without `outputPath`, since nothing is written beside the executable.
+
+1. Drop the two paths from the embedded call:
+
+   ```ts
+   // before
+   createNativePackaging({
+     platform: 'darwin', architecture: 'arm64', delivery: 'embedded',
+     entryPath: 'cli.js', assetPath: 'native/darwin-arm64.node',
+   })
+   // after
+   createNativePackaging({ platform: 'darwin', architecture: 'arm64', delivery: 'embedded' })
+   ```
+
+   Search pattern: `delivery: 'embedded'`.
+2. Code that read `asset.outputPath` from an embedded result reads `bytes`, `size` and `sha256`
+   only; an annotation `NativePackagingOptions` / `NativePackagingResult` on an embedded call
+   becomes `NativePackagingEmbeddedOptions` / `NativePackagingEmbeddedResult`.
+3. Rebuild every artifact made without the plugin by 0.105.0–0.106.1: it carries the build
+   machine's package path (see [Darwin native assets in JS distributions](#darwin-native-assets-in-js-distributions)).
+
 ## Released migration: 0.106.0
 
 ### a stopped leader settles as stopped
@@ -16180,13 +16439,27 @@ Custom output layout uses the evolving build-only packaging contract in the
 Three deliveries have different rules: an ordinary npm install retains the package's
 native assets; a JS distribution must ship its complete output graph; a Bun compiled
 executable embeds the matching addon and may still use `--outfile`. In 0.103.13–0.104.2 a plain
-`bun build` carries the addon without a plugin; later releases carry it only when the build
-uses `createNativePackaging` (`delivery: 'companion'` for JS, `'embedded'` for a compiled
-executable).
-The [native IO guide](native-io.md#libraries-with-a-zod-only-runtime) is the canonical recipe.
-Check the resulting artifact offline outside the build tree and `node_modules`, including
-process identity, live-owner lock refusal, dead-owner recovery and contained IO.
-A missing or corrupt addon remains `unavailable`, never evidence that an owner died.
+`bun build` carries the addon without a plugin. Later releases load it from a bundle only when
+the build uses `createNativePackaging` (`delivery: 'companion'` for JS, `'embedded'` for a
+compiled executable). Without the plugin, Bun may still copy the addon's bytes into a compiled
+executable, but the loader never uses them, so their presence proves nothing.
+
+What an unpackaged bundle does depends on the release:
+
+- **0.105.0–0.106.1:** the bundle carries the absolute path of the package on the build machine,
+  because the loader read `__dirname`. It looks for the addon there, so it works only on that
+  machine, and the path itself leaks into a distributed artifact. Rebuild with a later release.
+- **0.107.0 and later:** no build path is in the artifact, and the first call that needs the
+  addon reports the Darwin backend `unavailable` with stage `packaging`.
+
+Only macOS is affected, and only process identity (`observeProcessInstance`,
+`probeProcessOwner`), exclusive locks and contained Agent file operations load the addon. The
+managed file boundary, atomic writes and the chunk spool never do. The
+[native IO guide](native-io.md#libraries-with-a-zod-only-runtime) is the canonical recipe and
+shows how to check an artifact by its loader without running it on a Mac. Check the resulting
+artifact offline outside the build tree and `node_modules`, including process identity,
+live-owner lock refusal, dead-owner recovery and contained IO. A missing or corrupt addon
+remains `unavailable`, never evidence that an owner died.
 
 ### CLI: repeated options are refused
 
@@ -16783,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.
@@ -20270,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 |
@@ -22085,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 |
@@ -22194,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 |
@@ -22743,13 +23057,19 @@ Native POSIX Bun/Node one-shot command execution. See [native IO](../guide/nativ
 ## `stitchkit/files/packaging`
 
 `stitchkit/files/packaging` owns `createNativePackaging` and the types
-`NativePackagingOptions`, `NativePackagingAsset`, `NativePackagingPlugin`, `NativePackagingResult`.
+`NativePackagingOptions`, `NativePackagingAsset`, `NativePackagingPlugin`, `NativePackagingResult`,
+and for a standalone executable `NativePackagingEmbeddedOptions`, `NativePackagingEmbeddedAsset`,
+`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.
-`platform`, `architecture`, `delivery`, `entryPath` and `assetPath` are explicit public inputs;
-`assetPath` accepts one template, `[hash]`, replaced by the first 16 hex digits of the addon's
-published SHA256;
+`platform`, `architecture`, `delivery`, `entryPath` and `assetPath` are the explicit inputs of
+companion delivery; embedded delivery takes `platform`, one `architecture` and `delivery` only, and
+refuses a path. `assetPath` accepts one template, `[hash]`, replaced by the first 16 hex digits of
+the addon's published SHA256;
 `platform` is the closed set `'darwin'`, and another name is a type error and a schema refusal.
 The result is `ready` with verified assets and a structural Bun plugin, or `unsupported` /
 `missing` / `mismatch` with the safe code `NATIVE_TARGET_UNSUPPORTED`, `NATIVE_ASSET_MISSING` or
@@ -22766,7 +23086,8 @@ and the published `size` and `sha256`.
 Targets must be unique; entry and all asset paths must be disjoint. One lazy loader chooses only
 the actual runtime architecture, with no fallback.
 Companion mode places external addons relative to the emitted entry; embedded mode gives
-Bun compile the verified bytes of the matching addon. Keep JS builds without splitting, preserve
-every output, and write each asset's `bytes` to its `outputPath`.
+Bun compile the verified bytes of the matching addon, and its asset (`bytes`, `size`, `sha256`)
+has no `outputPath`, because nothing is written beside the executable. Keep companion JS builds
+without splitting, preserve every output, and write each asset's `bytes` to its `outputPath`.
 This evolving entrypoint is a build dependency; runtime imports do not reach it.
 The detailed recipe is in [native IO](../guide/native-io.md#public-native-packaging).