stitchkit 0.103.13 → 0.104.1

package/llms/{upgrading-0.75.0-0.103.0.txt → upgrading-0.81.0-0.104.0.txt}

@@ -1,14 +1,165 @@
-# Upgrading 0.75.0 → 0.103.0 — stitchkit docs slice
+# Upgrading 0.81.0 → 0.104.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.75.0 → 0.103.0  (docs/guide/upgrading.md)
+Contains: Guide: Upgrading, 0.81.0 → 0.104.0  (docs/guide/upgrading.md)
 
 ==============================================================================
-# Guide: Upgrading, 0.75.0 → 0.103.0  (docs/guide/upgrading.md)
+# Guide: Upgrading, 0.81.0 → 0.104.0  (docs/guide/upgrading.md)
 ==============================================================================
 
+## Released migration: 0.104.0
+
+JS bundles carrying Darwin native capabilities also need the
+[delivery migration first affected in 0.103.13](#released-migration-010313).
+Consumers upgrading from 0.103.12 or earlier must apply it even if their TypeScript API is unchanged.
+
+### CLI runtime-tool construction
+
+**Who must act:** callers writing a schema-dependent handler or MCP/AI `present` directly
+inside an annotated `CliConfig.runtimeTools` or `CliInvokerConfig.runtimeTools` object.
+Native `commands` and values returned by `defineRuntimeTool` / `createRuntimeToolFactory`
+remain valid. Execution, auth, validation and the invocation result envelope keep their behavior.
+
+Construct a CLI-only managed definition with the neutral schema-aware type before registration:
+
+```ts
+import type { CliInvokerConfig, RuntimeToolExecutionWithOutput } from 'stitchkit/cli'
+import { z } from 'zod'
+
+const input = z.object({ text: z.string() })
+const output = z.object({ size: z.number() })
+// Before: handler receives the heterogeneous registry context.
+const config: CliInvokerConfig = {
+  name: 'app',
+  runtimeTools: [{
+    name: 'measure', description: 'Measure text',
+    identity: { serviceName: 'text', action: 'measure', method: 'POST' },
+    transports: ['CLI'], input, output,
+    handler: ({ input }) => ({ size: String(input.text).length }),
+  }],
+}
+// After: handler input and output derive from the construction schemas.
+const measure = {
+  name: 'measure', description: 'Measure text',
+  identity: { serviceName: 'text', action: 'measure', method: 'POST' },
+  transports: ['CLI'], input, output,
+  handler: ({ input }) => ({ size: input.text.length }),
+} satisfies RuntimeToolExecutionWithOutput<typeof input, typeof output>
+const nextConfig: CliInvokerConfig = { name: 'app', runtimeTools: [measure] }
+```
+
+For a shared MCP/AI tool, construct the definition with `defineRuntimeTool` from
+`stitchkit/tools`, including its typed SDK `present` callbacks, then pass the returned value
+to `runtimeTools`. Install the corresponding SDK peers for that integration. A CLI-only
+consumer needs `stitchkit`, `zod` and its ordinary Node type tooling.
+
+`RuntimeToolExecution` names the heterogeneous registration contract. Call a registered
+operation through `createCli` or `createCliInvoker`; its erased handler input is `never`
+because the managed runner owns schema validation before execution. For a managed void
+definition, use `RuntimeToolDefinitionWithoutOutput<typeof input>`.
+
+### MCP construction, state stores and delivery
+
+**Who must act:** schema-dependent runtime tool literals written directly inside MCP mount
+configuration, MCP presenters returning malformed content or metadata, custom `StateStore`
+implementations, file-store consumers using retired lock
+options, broadcast consumers reading `halt` or retrying unknown send outcomes, and consumers
+that validate HTTP error envelopes with a closed schema. Applications collecting raw tool
+causes from `console.error` must configure an internal tool hook sink.
+
+MCP-only code can import the existing server factories from `stitchkit/tools/mcp` and
+construct its schema-aware tool before heterogeneous registration:
+
+```ts
+import { buildMcpServer, type RuntimeMcpToolDefinitionWithOutput } from 'stitchkit/tools/mcp'
+import { z } from 'zod'
+const input = z.object({ value: z.number() })
+const output = z.object({ doubled: z.number() })
+// Before: runtimeTools: [{ input, output, handler, present }]
+const double = {
+  name: 'double', description: 'Double a number',
+  identity: { serviceName: 'numbers', action: 'double', method: 'POST' },
+  input, output,
+  handler: ({ input }) => ({ doubled: input.value * 2 }),
+  present: { mcp: ({ doubled }) => ({ content: [{ type: 'text', text: String(doubled) }] }) },
+} satisfies RuntimeMcpToolDefinitionWithOutput<typeof input, typeof output>
+const server = buildMcpServer({ serverInfo: { name: 'numbers', version: '1' }, services: [], runtimeTools: [double] })
+```
+
+Full MCP/AI integrations keep `defineRuntimeTool` from `stitchkit/tools`; those typed values
+remain accepted by the MCP leaf and CLI. The leaf requires the MCP SDK and Zod, with no AI peer.
+
+`RuntimeMcpPresentation` preserves the official SDK's required `content` and typed `_meta`
+fields. A presenter returning `{}` must return `{ content: [] }`; text blocks require string
+text, and metadata must be an object. `structuredContent` and `isError` remain framework-owned.
+This restores SDK checks that an indexed mapped type previously erased.
+
+Unexpected tool causes remain in `hooks.onToolError` and the `error` field of
+`hooks.afterToolCall`. Protocol stderr carries safe errors. MCP resolver failures use those
+same observers without executing the handler or its lifecycle again. HTTP's default
+unexpected-error logging retains its behavior.
+
+A custom state adapter's `update` must invoke `transition(current, context)` while it still
+owns the serialized transaction. `context.assertHeld()` checks the actual transaction or lock
+generation and refuses after completion, rollback or ownership loss. A no-op guard cannot
+satisfy this contract. Existing transition callbacks may keep one parameter. For the owning
+file adapter, replace `{ staleLockMs, retryMs, lockTimeoutMs }` with `{ lockTimeoutMs }`:
+the remaining budget controls acquisition waiting, never expiry of a live transaction.
+Unknown legacy PID locks and historical temporary files are preserved; recover them only
+after independently proving their owner is gone.
+
+Broadcast consumers change `report.halt.reason` checks to the closed `halt.kind` union:
+`retry-after`, `transient`, `permanent` or `ambiguous`. A custom MTProto adapter can classify
+an acknowledged flood refusal as `{ kind: 'retry-after', retryAfterMs: wait }`; the exact
+provider wait is respected. A wait over `maxRetryDelayMs` halts with the recipient pending.
+Unknown write outcome becomes `uncertain`; restarting the same broadcast does not send it
+again. A retry classification must certify that the attempt did not apply the external effect.
+
+HTTP errors gain optional boolean `error.retryable`; framed contract streams use the same
+field. Update closed consumer schemas before producers declaring it. `false` on 502 and
+`true` on 409 remain explicit recommendations through the remote tool path. An absent field
+retains prior status-derived defaults; the field does not change the HTTP client's retry policy.
+The existing seventh `ApiError` constructor argument remains `ErrorOptions`; retryability is
+the new eighth argument.
+
+Caller cancellation now reaches `implementRemote`'s existing HTTP call. Applications bind
+signals to `createCli` / `createCliInvoker` and cooperative handlers observe `ctx.signal`.
+`REQUEST_ABORTED` is nonretryable and exits 130. A disconnected caller does not prove that
+an origin ignoring cancellation or an external provider stopped; keep resource leases until
+that work actually completes.
+
+## Released migration: 0.103.13
+
+### Darwin native assets in JS distributions
+
+**Who must act:** Bun JS builds using `--outfile`, copying only `outputs[0]`, custom
+single-file/archive packagers and installers delivering native process/files capabilities.
+First affected publication: **0.103.13**. It shipped as a patch; its changed delivery graph
+requires this migration despite unchanged API signatures.
+
+```sh
+# Before: one JS file was assumed to be the entire distribution.
+bun build src/native.ts --target=bun --outfile=dist/native.js
+# After: retain every output, with its relative path.
+bun build src/native.ts --target=bun --outdir=dist --entry-naming=native.js
+```
+
+For `Bun.build`, copy **all** `result.outputs`, not just the JS entry or `outputs[0]`.
+A single-file JS distribution cannot embed a native `.node` addon automatically.
+An archive may contain JS plus companion assets, materialized together before execution.
+Custom output layout uses the evolving build-only packaging contract in the
+[native IO guide](native-io.md#public-native-packaging).
+
+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`.
+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.
+
 ## Released migration: 0.103.0
 
 ### Diagnostic journal startup preserves torn evidence and inspects archives
@@ -901,217 +1052,3 @@ compile error instead of building a URL with an unresolved segment. Measured
 across three consuming applications before release (373 endpoints with path
 segments), no explicit schema missed a field: the migration is deleting
 schemas that only repeated the path, or nothing.
-
-## Released migration: 0.80.0
-
-One thing, and only if you parse an async-operation snapshot.
-
-```bash
-rg -n "createAsyncOperationSnapshotSchema"
-```
-
-`progress` on a parsed snapshot used to be `unknown`. The factory built its
-object shapes with a conditional spread, and the narrowing inside it widened
-your schema back to a bare `ZodType`, so the emitted declaration threw the type
-argument away. It is now the output of the schema you configured.
-
-```ts
-const schema = createAsyncOperationSnapshotSchema({
-  progress: z.object({ done: z.number(), total: z.number() }),
-  failure: z.object({ code: z.string() }),
-})
-const snap = schema.parse(body)
-if (snap.phase === 'running') {
-  // before: `snap.progress` was `unknown` — this needed a cast or a narrow
-  // after:  it is `{ done: number; total: number } | undefined`
-  console.log(snap.progress?.done)
-}
-```
-
-**If you cast it**, delete the cast — it was working around the erased type.
-**If you assigned something else to it**, the compiler now refuses, and it was
-already a value the schema rejected at run time.
-
-**If you pass explicit type arguments**, the no-progress form takes one now, not
-two: the factory is two overloads. Pass none.
-
-```ts
-// before: createAsyncOperationSnapshotSchema<undefined, typeof Failure>({ failure: Failure })
-// after:  createAsyncOperationSnapshotSchema({ failure: Failure })
-```
-
-Nothing about parsing moves. A snapshot configured without `progress` still
-strips an unexpected `progress` rather than refusing it — that behaviour is why
-this is overloads and not one normalised key.
-
-**If you compile with `skipLibCheck: false`**, this is also the release that
-makes `stitchkit/tools/contract` compile at all: it carried five `TS2344`
-errors, one per phase, from the same conditional spread.
-
-## Released migration: 0.79.0
-
-One thing, and only if you assert on the whole snapshot.
-
-```bash
-rg -n "getSnapshot\(\)|projectApplicationStatus|status\(\)" --glob '*.test.ts' --glob '*.spec.ts'
-```
-
-`ApplicationSnapshot` and `ApplicationStatusProjection` each gained a
-`restarting` field — ids in the snapshot, a count in the projection. A reader
-that names the fields it wants is unaffected. A test that compares the whole
-object with `toEqual` fails until it adds the field:
-
-```ts
-// before
-expect(body).toEqual({ id, lifecycle: 'ready', /* … */ resources: { total: 1, ready: 1, degraded: 0, failed: 0 } })
-// after
-expect(body).toEqual({ id, lifecycle: 'ready', /* … */ resources: { total: 1, ready: 1, degraded: 0, failed: 0 }, restarting: 0 })
-```
-
-It is zero except while a restart is running, and then it names the subtree being
-replaced. That is the point: a snapshot taken mid-restart used to be
-indistinguishable from a resource that had failed on its own, so a dashboard read
-a planned replacement as an outage.
-
-**If you watch a hub across a restart**, nothing to change, but the behaviour is
-different and better: closing a hub now tells its subscribers `unavailable` /
-`source-unavailable` instead of dropping them, so a page stops showing a value
-that will never update again.
-
-**If you need a tool contract in a browser**, `stitchkit/tools/contract` now
-carries the async-operation helpers, its schemas and the view-file input/output
-without the runtime. `stitchkit/tools` still exports all of them.
-
-## Released migration: 0.78.0
-
-Two mechanical edits. Find them both:
-
-```bash
-rg -n "createDecisionPipeline|createDiagnosticJournal" --glob '*.ts' --glob '*.tsx'
-```
-
-**1. `createDecisionPipeline` takes a deadline.**
-
-```ts
-// before
-createDecisionPipeline([policyA, policyB])
-// after
-createDecisionPipeline([policyA, policyB], { policyTimeoutMs: 2_000 })
-```
-
-Pick a number your slowest policy comfortably beats. There is no default on
-purpose: a policy that never settles hangs every caller of the operation it
-guards, and the framework has no basis for choosing that number for you.
-
-Past the deadline — and on a throw, and on a non-decision — the pipeline raises
-`DecisionPolicyError` naming the policy, with the trace so far. If you already
-catch that for a bad return value, you now catch two more cases with it.
-
-**2. `createDiagnosticJournal` moved.**
-
-```ts
-// before
-import { createDiagnosticJournal } from 'stitchkit/application'
-// after
-import { createDiagnosticJournal } from 'stitchkit/application/diagnostic-journal'
-```
-
-Only the factory moved. `DiagnosticJournalConfig`, every
-`DiagnosticJournal*Schema` and `readDiagnosticJournalLockDiagnosis` stay where
-they were.
-
-**If you restart resources**, nothing to change — but three things that did not
-work now do: a managed schedule can be restarted, a restarted keyspace accepts
-writes again, and a restarted managed server is actually shut down at exit. If
-you pass `managedServerResource` a server *instance*, a restart is now refused
-by name; pass a factory (`server: (context) => …`) to restart it.
-
-## Released migration: 0.77.0
-
-Two type renames, and only if you named them. Nothing runtime moved.
-
-```bash
-rg -n "EventDecision|EventUndecided" --glob '*.ts' --glob '*.tsx'
-```
-
-```ts
-// before
-import type { EventDecision, EventUndecided } from 'stitchkit/live'
-// after
-import type { PolicyDecision, UndecidedOutcome } from 'stitchkit/live'
-```
-
-The shapes are identical — `{ outcome: 'allow' } | { outcome: 'deny', reason } | { outcome: 'defer' }`
-and `'allow' | 'deny'`. If you only ever *return* decisions from listeners and never named the
-type, the search above finds nothing and there is nothing to do.
-
-They were renamed because `createDecisionPipeline` (new in this release) votes with exactly the
-same three outcomes, and two identical types under two names is the thing that makes a search for
-either one return half the truth.
-
-## Released migration: 0.76.0
-
-One change, and only if you hand `createWatchClient` a transport you wrote yourself.
-
-```bash
-rg -n "createWatchClient" --glob '*.ts'
-```
-
-If the `transport:` you pass is a bound realtime client — `bindRealtimeClient(...)` or
-`createRealtimeClient(...)` — there is nothing to do: it already carries
-`onConnectionChange`. If it is an object you assembled, add the fourth member:
-
-```ts
-onConnectionChange(listener: (connected: boolean, reason?: string) => void): () => void
-```
-
-It is required because the client recovers through it: on a drop it publishes
-`unavailable` to subscribers and forgets what was opened, and on a fresh
-connection it re-opens every key that still has a listener. Without it a watch
-stays "open" on the client after a server restart while the hub remembers
-nothing, and the face stops updating without saying so.
-
-## Released migration: 0.75.0
-
-Two mechanical renames and one option that has to move. Nothing about a passing
-request changes.
-
-### 1. A route group's `onRequest`
-
-```bash
-rg -n "hooks:\s*\{[^}]*onRequest" --glob '*.ts'
-```
-
-Any match **inside a `groups: [...]` entry** must move. The hook was accepted and
-never dispatched, so the behaviour you have today is "no hook"; the fix is to
-decide which one you meant:
-
-```ts
-// refuse before dispatch, for the whole server
-createServer({ groups, hooks: { onRequest: gate } });
-
-// gate this group once the endpoint is known
-groups: [{ pathPrefix: '/admin', services, hooks: { authorize: gate } }]
-```
-
-A group that still declares `onRequest` fails at startup with that message.
-
-### 2. The SQLite boundary type
-
-```bash
-rg -l "AgentRuntimeSqlite(Database|Statement|Value)" | xargs sed -i \
-  -e 's/AgentRuntimeSqliteDatabase/SqliteDatabase/g' \
-  -e 's/AgentRuntimeSqliteStatement/SqliteStatement/g' \
-  -e 's/AgentRuntimeSqliteValue/SqliteValue/g'
-```
-
-Type-only: the same three methods, the same structural compatibility with
-`bun:sqlite` and a `node:sqlite` wrapper, imported from the same entrypoints.
-`initializeAgentRuntimeSqlite` keeps its name — it really is the agent runtime's
-schema.
-
-### 3. Nothing else
-
-`stitchkit/live`, the watch hub, the keyspace and the trust fence are all
-additive. Adopt them when you want them; the guide is
-[Live data](./live.md).

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.75.0 → 0.103.0: `llms/upgrading-0.75.0-0.103.0.txt`
-- 0.61.0 → 0.74.0: `llms/upgrading-0.61.0-0.74.0.txt`
-- 0.44.0 → 0.60.0: `llms/upgrading-0.44.0-0.60.0.txt`
-- 0.37.0 → 0.37.0: `llms/upgrading-0.37.0.txt`
+- 0.81.0 → 0.104.0: `llms/upgrading-0.81.0-0.104.0.txt`
+- 0.62.0 → 0.80.0: `llms/upgrading-0.62.0-0.80.0.txt`
+- 0.44.0 → 0.61.0: `llms/upgrading-0.44.0-0.61.0.txt`
+- 0.37.0 → 0.44.0: `llms/upgrading-0.37.0-0.44.0.txt`
 
 # Upgrading stitchkit