stitchkit 0.107.0 → 0.108.1

package/llms/telegram.txt

@@ -234,8 +234,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
@@ -254,6 +254,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
@@ -453,7 +483,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 |

package/llms/testing.txt

@@ -223,6 +223,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
@@ -617,6 +661,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 |

package/llms/{upgrading-0.98.0-0.107.0.txt → upgrading-0.100.0-0.108.0.txt}

@@ -1,14 +1,70 @@
-# Upgrading 0.98.0 → 0.107.0 — stitchkit docs slice
+# Upgrading 0.100.0 → 0.108.0 — stitchkit docs slice
 
 > Generated from the `docs/` tree by `bun run gen:llms`. The index of all slices is
 > `llms.txt` in this package.
 
-Contains: Guide: Upgrading, 0.98.0 → 0.107.0  (docs/guide/upgrading.md)
+Contains: Guide: Upgrading, 0.100.0 → 0.108.0  (docs/guide/upgrading.md)
 
 ==============================================================================
-# Guide: Upgrading, 0.98.0 → 0.107.0  (docs/guide/upgrading.md)
+# Guide: Upgrading, 0.100.0 → 0.108.0  (docs/guide/upgrading.md)
 ==============================================================================
 
+## 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
@@ -844,64 +900,3 @@ recovery refuses rather than treating unknown ownership as death. From 0.100.1 a
 Linux kernel without time namespaces (before 5.6) records the PID namespace alone
 instead of null, so its locks recover like any other. Existing
 `refuse` policy and the separately configured ownerless-file grace are unchanged.
-
-## Released migration: 0.99.0
-
-### structural alternatives in flattened tool schemas
-
-**Who must act:** applications using `flattenUnionInput: true` with schema
-walkers, snapshots or provider restrictions that assume there is no nested
-`anyOf`. Applications without that assumption need only update the dependency.
-
-Colliding object/array fields retain their complete structural alternatives:
-
-```ts
-// Before: loses both field vocabulary and array items.
-{ type: ['object', 'array'] }
-// After: structural alternatives live inside the property schema.
-{ anyOf: [
-  { type: 'array', items: {
-    type: 'object', properties: { id: { type: 'string' } }, required: ['id'],
-  } },
-  { type: 'object', properties: { id: { type: 'string' } }, required: ['id'] },
-] }
-```
-
-Alternatives come in kind order, independent of variant order. The same shape
-covers every collision of different kinds, scalars included: `string` against
-`string[]` becomes `{ anyOf: [{ type: 'array', items: { type: 'string' } }, { type:
-'string' }] }`. A nullable field keeps `null` in each alternative's `type`, and
-differing nested object unions remain nested `anyOf` inside the alternatives. Update
-snapshots to this order.
-
-Traverse each nested alternative when inspecting schemas and regenerate schema
-snapshots. Verify the actual manifest with the chosen provider. Keep flatten
-enabled when a top-level discriminated union needs to be advertised as an
-object; do not erase `items` or introduce consumer-specific schema patches.
-The root object, discriminator enum, requiredness hints and strict runtime
-contract validation are unchanged. See ADR 0205.
-
-## Released migration: 0.98.0
-
-### automatic stdin availability
-
-**Who must act:** CLI applications or scripts relying on automatic stdin routing
-from a producer that can take more than 250 ms to write its first byte.
-
-Automatic routing now probes for the first byte for 250 ms. An empty open pipe
-leaves the required field unset and normal validation reports its name. Once
-data arrives, the entire stream is read until EOF without a total deadline.
-
-```sh
-# before: may now fail if the producer starts late
-slow-producer | myapp generate
-# after: provide the value explicitly after the producer completes
-myapp generate --prompt "$(slow-producer)"
-```
-
-For large input that should stay in a pipe, supply a `CliConfig.stdin` reader
-that waits for the producer and EOF; this existing hook is not wrapped in the
-availability probe. A custom reader owns its limits and error handling.
-`-` remains literal data. TTY and empty EOF produce ordinary validation errors;
-explicit arguments skip stdin. JSONL stream/batch commands, MCP/serve and
-long-running handlers have no new deadline. See ADR 0203.

package/llms/{upgrading-0.72.0-0.97.0.txt → upgrading-0.72.0-0.99.0.txt}

@@ -1,14 +1,75 @@
-# Upgrading 0.72.0 → 0.97.0 — stitchkit docs slice
+# Upgrading 0.72.0 → 0.99.0 — stitchkit docs slice
 
 > Generated from the `docs/` tree by `bun run gen:llms`. The index of all slices is
 > `llms.txt` in this package.
 
-Contains: Guide: Upgrading, 0.72.0 → 0.97.0  (docs/guide/upgrading.md)
+Contains: Guide: Upgrading, 0.72.0 → 0.99.0  (docs/guide/upgrading.md)
 
 ==============================================================================
-# Guide: Upgrading, 0.72.0 → 0.97.0  (docs/guide/upgrading.md)
+# Guide: Upgrading, 0.72.0 → 0.99.0  (docs/guide/upgrading.md)
 ==============================================================================
 
+## Released migration: 0.99.0
+
+### structural alternatives in flattened tool schemas
+
+**Who must act:** applications using `flattenUnionInput: true` with schema
+walkers, snapshots or provider restrictions that assume there is no nested
+`anyOf`. Applications without that assumption need only update the dependency.
+
+Colliding object/array fields retain their complete structural alternatives:
+
+```ts
+// Before: loses both field vocabulary and array items.
+{ type: ['object', 'array'] }
+// After: structural alternatives live inside the property schema.
+{ anyOf: [
+  { type: 'array', items: {
+    type: 'object', properties: { id: { type: 'string' } }, required: ['id'],
+  } },
+  { type: 'object', properties: { id: { type: 'string' } }, required: ['id'] },
+] }
+```
+
+Alternatives come in kind order, independent of variant order. The same shape
+covers every collision of different kinds, scalars included: `string` against
+`string[]` becomes `{ anyOf: [{ type: 'array', items: { type: 'string' } }, { type:
+'string' }] }`. A nullable field keeps `null` in each alternative's `type`, and
+differing nested object unions remain nested `anyOf` inside the alternatives. Update
+snapshots to this order.
+
+Traverse each nested alternative when inspecting schemas and regenerate schema
+snapshots. Verify the actual manifest with the chosen provider. Keep flatten
+enabled when a top-level discriminated union needs to be advertised as an
+object; do not erase `items` or introduce consumer-specific schema patches.
+The root object, discriminator enum, requiredness hints and strict runtime
+contract validation are unchanged. See ADR 0205.
+
+## Released migration: 0.98.0
+
+### automatic stdin availability
+
+**Who must act:** CLI applications or scripts relying on automatic stdin routing
+from a producer that can take more than 250 ms to write its first byte.
+
+Automatic routing now probes for the first byte for 250 ms. An empty open pipe
+leaves the required field unset and normal validation reports its name. Once
+data arrives, the entire stream is read until EOF without a total deadline.
+
+```sh
+# before: may now fail if the producer starts late
+slow-producer | myapp generate
+# after: provide the value explicitly after the producer completes
+myapp generate --prompt "$(slow-producer)"
+```
+
+For large input that should stay in a pipe, supply a `CliConfig.stdin` reader
+that waits for the producer and EOF; this existing hook is not wrapped in the
+availability probe. A custom reader owns its limits and error handling.
+`-` remains literal data. TTY and empty EOF produce ordinary validation errors;
+explicit arguments skip stdin. JSONL stream/batch commands, MCP/serve and
+long-running handlers have no new deadline. See ADR 0203.
+
 ## Released migration: 0.97.0
 
 ### schedule delivery

package/llms/upgrading.txt

@@ -11,8 +11,8 @@ Contains: Guide: Upgrading, general  (docs/guide/upgrading.md)
 
 Load this slice, then every range slice between your installed version and the target:
 
-- 0.98.0 → 0.107.0: `llms/upgrading-0.98.0-0.107.0.txt`
-- 0.72.0 → 0.97.0: `llms/upgrading-0.72.0-0.97.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`
 
@@ -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`,