stitchkit 0.93.0 → 0.94.1

package/llms/upgrading.txt

@@ -0,0 +1,215 @@
+# Upgrading — how to move across versions — 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, general  (docs/guide/upgrading.md)
+
+==============================================================================
+# Guide: Upgrading, general  (docs/guide/upgrading.md)
+==============================================================================
+
+Load this slice, then every range slice between your installed version and the target:
+
+- 0.68.0 → 0.94.0: `llms/upgrading-0.68.0-0.94.0.txt`
+- 0.53.0 → 0.67.0: `llms/upgrading-0.53.0-0.67.0.txt`
+- 0.37.0 → 0.50.0: `llms/upgrading-0.37.0-0.50.0.txt`
+
+# Upgrading stitchkit
+
+## The one rule that makes this work
+
+A release that breaks a public API leads its `CHANGELOG.md` entry with a
+**`### ⚠️ Breaking changes`** section (exact heading), each item carrying a
+**before → after** snippet. A version with **no** such section is **purely
+additive** — adopting it changes nothing in your code. (See
+[`AGENTS.md` → Breaking changes](../../AGENTS.md).) So the list is recoverable
+mechanically, and the package recovers it for you:
+
+```bash
+bunx stitchkit@latest upgrade    # or: npx stitchkit@latest upgrade
+```
+
+Run it inside the project that depends on stitchkit. It reads your installed
+version out of `node_modules`, reads the changelog **shipped inside the
+package**, and prints every breaking section your range crosses, oldest first,
+each with its **Who must act** line — the list this guide's migrations expand
+on. Nothing to clone, nothing to be told: `--from` / `--to` override either end
+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.
+
+## 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`,
+so a plain `install` picks up every patch — fixes, new API, no code changes —
+and **never** crosses a minor. Crossing one is always something you chose.
+
+**An exact pin (`"stitchkit": "0.71.0"`) is a different arrangement, and it is
+easy to mistake for a safer version of the same one.** It does not opt you out
+of breaking changes; it opts you out of *every* change, patches included. No
+install will move you, nothing will warn you, and the gap grows quietly — a
+project pinned exactly for a few months is typically several minors behind and
+has had no signal at all that this is so. That is a legitimate choice, but it
+makes one thing your job rather than the resolver's:
+
+- **Check deliberately.** `npm view stitchkit version` against your pin, on
+  whatever cadence suits the project. Nothing else will raise it.
+- **Then upgrade across the whole gap at once**, exactly as below: apply the
+  `### ⚠️ Breaking changes` of every version above your pin up to your target,
+  in order. A pin held across four minors is four migrations, not one, and
+  three of them may be a single snippet each.
+
+The mechanical part is identical either way. Only the *noticing* differs, and an
+exact pin moves it onto you.
+
+## Before you bump, if you implement an agent store
+
+One step, and it is mechanical. If your project has an `AgentRuntimeStore` — a
+Prisma adapter, an in-memory one, anything — run the conformance kit against it
+**on the version you are leaving**, then again after the bump:
+
+```ts
+import { runAgentStoreConformance } from 'stitchkit/testing'
+
+await runAgentStoreConformance({ createStore: () => yourStore })
+```
+
+The kit picks the conversation identities itself and hands them over **before**
+the first mutation, so a store whose runtime rows hang off an application-owned
+conversation row can provision the parents — and take them away again:
+
+```ts
+await runAgentStoreConformance({
+  createStore: (context) => {
+    for (const conversationId of context.conversationIds) createConversationRow(conversationId)
+    return yourStore
+  },
+  cleanup: (context) => {
+    for (const conversationId of context.conversationIds) deleteConversationRow(conversationId)
+  },
+})
+```
+
+`cleanup` runs exactly once, after the scenario, whether it passed or failed —
+and a failure in it never replaces the scenario's own.
+
+Green before and red after tells you the contract grew and where, in one run,
+instead of one failure at a time in production. Green both times means the
+upgrade owes you nothing on that surface — which is the usual answer if you
+implement `AgentRuntimeStoreDriver` and compose the aggregate with
+`createAgentRuntimeStore(driver)`, the supported shape (→ ADR 0111).
+
+## Flow (agent or human)
+
+1. **Find the current version.** In the consumer: the resolved `stitchkit` in
+   `bun.lock` (authoritative), or `node_modules/stitchkit/package.json`. The range
+   in `package.json` (`^0.6.0`) is intent, not the installed truth.
+   > A `file:` link (`"stitchkit": "file:…"`) means the consumer tracks a **local
+   > checkout**, not a published version — its effective version is whatever that
+   > checkout's `package.json` says, and a plain `install` will not relink it after
+   > the local version moves (`bun install --force` does). Prefer a real
+   > `^x.y.z` range for reproducibility.
+
+2. **Pick the target.** Latest published (`bun pm view stitchkit version`) or a
+   specific `x.y.z`.
+
+3. **Read the breaking sections in range.** In stitchkit's
+   [`CHANGELOG.md`](../../CHANGELOG.md), for every version `> current` and
+   `<= target`, read its `### ⚠️ Breaking changes`. Versions without that section
+   are additive — skip them. (Fast scan: `grep -n "Breaking changes" CHANGELOG.md`.)
+
+4. **Apply each migration** — the before → after snippet tells you exactly what to
+   change at each call site. There are no deprecation shims to lean on; the old
+   shape is gone, so every site must move.
+
+   Then read this file's **`## Released migration: X.Y.Z`** section for each of
+   those versions. That is the half the changelog does not carry: what else
+   stops working because of the change, and what changes *silently* rather than
+   at compile time — projected history returning fewer messages, a dashboard
+   field going blank. `bun run check` in step 6 cannot see either.
+
+5. **Bump and install.** `bun add stitchkit@<target>` (or update the range), then
+   `bun install`. Note the caret: `^0.7.0` is `< 0.8.0`, so crossing a breaking
+   minor is always an explicit version bump, never automatic.
+
+6. **Verify.** `bun run check` (or per-package typecheck) — TypeScript catches the
+   removed/renamed/retyped surfaces. Then a **runtime smoke** (typecheck ≠
+   runtime): bootstrap the server, one HTTP request, and any feature you rely on
+   (Socket.IO connect, an MCP tool call, a multipart upload, …).
+
+## Worked example — frozen on 0.3, jumping to 0.7
+
+1. `bun.lock` → consumer resolves `stitchkit@0.3.x`.
+2. Target: `0.7.0`.
+3. Scan CHANGELOG `### ⚠️ Breaking changes` for 0.4.0 … 0.7.0 → **none** (every
+   release was additive — new exports, an extra hook argument, opt-in fields).
+4. Nothing to migrate.
+5. `bun add stitchkit@^0.7.0`, `bun install`.
+6. `bun run check` green → runtime smoke → done. New surfaces
+   (`STITCH_ERROR_STATUS`, `serveFile`, `scopePrefixes`, `afterToolCall`'s
+   `MethodDef`, `maxUploadBytes`) are available to adopt, not required.
+
+## Your handlers may be returning more than the contract declares
+
+stitchkit validates every handler's return value against the endpoint's `output`
+schema and **passes on the parsed result** — so any field the schema does not
+declare is silently removed. That is deliberate (the contract is the published
+shape of the response), but when you are moving a *live* API onto stitchkit it is
+invisible: TypeScript does not reject excess properties, nothing logs it, and the
+client just receives fewer fields.
+
+While migrating, turn the diagnostic on:
+
+```ts
+createServer({ services, warnOnOutputStrip: true })   // off by default
+```
+
+Every removed key is logged as a dot-path with the endpoint that produced it
+(`notes.get: secret, nested.alsoSecret`). Tool transports strip identically —
+`mountMcp` / `mountAgent` take `onOutputStrip: (toolName, paths) => …`. Read the
+list, then either widen the contract or stop returning the field, and turn the
+flag back off: it is for the migration window, not for production.
+
+## Tool names may shift between versions
+
+Derived tool names are part of your public surface — an MCP client config or an
+agent prompt refers to them by string. Before and after any upgrade that touches
+name derivation, diff them mechanically:
+
+```ts
+import { listToolNames } from 'stitchkit/tools'
+console.log(JSON.stringify(listToolNames({ services, runtimeTools }), null, 2))
+```
+
+`listToolNames` never throws on an illegal name — that is deliberate, so it can
+show you the offending row when a mount would refuse it. Pin it in a snapshot
+test and a shift fails your build instead of your clients.
+
+## When you author a breaking change in stitchkit
+
+You are on the other side of this flow — see
+[`AGENTS.md` → Breaking changes & migration](../../AGENTS.md). In short: it is
+allowed; write the `### ⚠️ Breaking changes` block with a before → after snippet,
+bump the minor (pre-1.0), and migrate the controlled consumers in the same pass.
+
+### Where the migration section goes while the version has no number
+
+Write it here, immediately under the flow above, as
+**`## Unreleased migration: <short slug>`**. The slug matters: several unreleased
+migrations may sit side by side, and each one belongs to whoever wrote it. Do
+**not** reuse an existing `Unreleased migration` heading for a different change —
+that is how the 0.57.0 migration was lost, overwritten by the next author before
+anyone promoted it.
+
+At release, the release commit promotes every `Unreleased migration` heading into
+one `## Released migration: X.Y.Z`, each former heading becoming a `###`
+subsection under it. This is the same move the changelog makes when `[Unreleased]`
+becomes `## [X.Y.Z]`, and it happens in the same commit.
+
+A release carrying `### ⚠️ Breaking changes` and no matching
+`## Released migration: X.Y.Z` is refused by `bun scripts/release-plan.ts` — in
+`pre-push` and again in the publishing workflow. The check starts at `0.44.0`;
+breaking versions older than that are covered by the summary sections near the
+end of this file.