stitchkit 0.73.0 → 0.74.1

package/dist/remote.js

@@ -1,7 +1,7 @@
 import {
   ApiError,
   createClient
-} from "./index-0tfm7beg.js";
+} from "./index-58jzmnn4.js";
 import"./index-1rxswfbv.js";
 import"./index-nt1mp8km.js";
 import {

package/dist/testing.js

@@ -24,7 +24,7 @@ import {
 import {
   createClient,
   createClients
-} from "./index-0tfm7beg.js";
+} from "./index-58jzmnn4.js";
 import"./index-1rxswfbv.js";
 import"./index-nt1mp8km.js";
 import {

package/llms-full.txt

@@ -61,7 +61,7 @@ own, recorded as an ADR.
 | `stitchkit/testing` | tests on Bun or Node | stable | in-process generated clients over a real Fetch handler, plus the store and managed-resource conformance kits |
 | `stitchkit/declaration` | build and deployment tooling (Bun or Node) | evolving | `ProjectDeclarationSchema` — the one machine-readable statement a repository makes about itself |
 | `stitchkit/react` | browser | stable | `createCursorQuery`, `createCacheBridge` |
-| `stitchkit/agent-runtime` | server | evolving<br>_redefined in 10 of the 18 minors since 0.56.2, most recently 0.69.0_ | optional durable conversation/run loop, history, models, prompts, fencing and events |
+| `stitchkit/agent-runtime` | server | evolving<br>_redefined in 10 of the 19 minors since 0.56.2, most recently 0.69.0_ | optional durable conversation/run loop, history, models, prompts, fencing and events |
 | `stitchkit/agent-runtime/harness` | server | evolving | resource-aware process-local facade over the canonical Agent runtime; supervision stays outside |
 | `stitchkit/agent-runtime/coding-tools` | server (Bun or Node) | evolving | bounded host-authorized direct file and shell tools; a root boundary, not an OS sandbox |
 | `stitchkit/agent-runtime/openrouter` | server | evolving | isolated OpenRouter language-model adapter |
@@ -69,7 +69,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` | server | evolving<br>_redefined in 4 of the 18 minors since 0.56.2, most recently 0.72.0_ | managed resource graph, readiness, admission, schedules and bounded shutdown |
+| `stitchkit/application` | server | evolving<br>_redefined in 4 of the 19 minors since 0.56.2, most recently 0.72.0_ | managed resource graph, readiness, admission, schedules and bounded shutdown |
 | `stitchkit/application/grammy` | server | evolving | isolated grammY polling and webhook lifecycle adapters |
 | `stitchkit/application/opentelemetry` | server | evolving | maps application snapshots onto an injected OpenTelemetry `Meter` |
 
@@ -2098,19 +2098,55 @@ naming every offending field in the `message` and again in `details.issues` as
 `{ path, code, message }`. That holds for a JSON body, a query string and a path
 parameter alike, so a rejected argument always costs a round trip.
 
-An application that needs a local refusal can parse the schema itself before
-calling — `contract.endpoints.<name>.input` is the same Zod object the server
-validates with:
+It is tempting to close that gap locally: the schemas are on the contract object,
+and `input` is the very Zod object the server validates with, so parsing it before
+the call looks free. **It is not, and it fails in the direction that breaks
+working code.** A call's arguments and the server's `input` are not the same
+value, for two independent reasons.
+
+An argument object is typed as the intersection of `params`, `input` and any
+multipart fields, so `input` covers one factor of it. Parsed over the whole
+object it silently strips the keys it does not own — or, being `.strict()`,
+refuses them:
+
+```ts
+// params: { id }, input: z.object({ text }).strict()
+contract.endpoints.update.input.safeParse({ id: 'item-1', text: 'hello' })
+// → refused: unrecognized_keys: ["id"]     the server accepts this call
+```
+
+And on a query string or a multipart body the wire carries strings while the
+caller holds live values, so a coercing schema answers differently on each side:
 
 ```ts
-const parsed = contract.endpoints.create.input.safeParse(args)
-if (!parsed.success) return refuse(parsed.error)
-await api.create(args)
+// input: z.object({ flag: z.coerce.boolean() })
+api.list({ flag: false })
+// local  safeParse({ flag: false })   → false
+// server safeParse({ flag: 'false' }) → true      z.coerce.boolean()('false') is true
 ```
 
-It then owns a second error shape beside this one, so make the local refusal name
-the offending fields too. A caller who receives a bare code with no text cannot
-tell which gate refused or why — and reads it as a refusal of permission.
+And a plain JSON body is not the safe exception it looks like, because it still
+crosses `JSON.stringify`. A schema holding any type that does not survive that
+round trip — `z.date()`, `z.map()`, `z.set()`, `z.bigint()`, `z.instanceof(...)`,
+or `NaN` / `Infinity` inside a `z.number()` — agrees locally and refuses on the
+server:
+
+```ts
+// input: z.object({ when: z.date() }), POST, no path params
+check({ when: new Date() })   // accepted: a live Date
+// server                     // refused: expected date, received string
+```
+
+This one fails in the safe direction — nothing valid is blocked — but "safe" is
+about traffic, not about diagnostics. The check stays silent exactly where it
+promised to speak: the refusal then arrives from the server, through a different
+path and without the field names the local gate would have given. A gate that
+lets through what it was added to catch is not a cheap gate, it is a quiet one.
+
+One schema, one call, opposite answers — inside a single release, with no version
+skew involved. Argument validation therefore stays on the server, which is the
+only side that sees what was actually sent. A rejected argument costs a round
+trip, and the refusal names every offending field.
 
 An explicit contract `HEAD` operation is exposed like any other typed method.
 Because HEAD endpoints are `rawResponse`, it resolves to the untouched
@@ -2184,10 +2220,20 @@ the same client-only errors:
 
 | Failure | `ApiError.code` | `status` |
 |---------|-----------------|----------|
+| arguments refused before sending | `VALIDATION_ERROR` | `0` |
 | caller `AbortSignal` | `REQUEST_ABORTED` | `0` |
 | endpoint/client timeout | `REQUEST_TIMEOUT` | `0` |
 | other transport failure | `UNKNOWN_ERROR` | `0` |
 
+`status: 0` is what separates a refusal made here from one made by the server:
+the same `VALIDATION_ERROR` arrives with `400` when the server refused, and
+`details.issues` is the same `{ path, code, message }` array either way, so one
+rendering serves both. A refusal raised here is always a **rejection** — on both
+transports, for every call shape — and it never reaches the server. The client
+refuses this way for a missing path param, a missing scoped prefix key, a
+non-flat field in a `GET` input, and a missing or invalid multipart file. → ADR
+0148.
+
 Abort and timeout do not emit `network_error` and are not retried. The same
 options work for query, JSON, multipart and raw-response calls. Stitchkit does
 not expose upload progress: Fetch has no portable upload-progress primitive.
@@ -2231,9 +2277,16 @@ const work = createClient(requestWorkContract, {
 
 The same adapter accepts unrelated contract shapes without learning their DTOs
 or operation inventory. `createClient` chooses method/path from the contract,
-serializes only the declared arguments, forwards `.withOptions(..., { signal })`
-and validates the response through the endpoint's output schema. A caller payload
-cannot replace the configured base URL or reserved operation path.
+forwards `.withOptions(..., { signal })` and validates the response through the
+endpoint's output schema. A caller payload cannot replace the configured base URL
+or reserved operation path.
+
+It does **not** filter your arguments down to the declared ones. Keys the contract
+does not declare are consumed for the path where they belong there and otherwise
+sent as they are — `api.list({ q: 'hello', note: 'internal' })` puts
+`?q=hello&note=internal` on the wire, and the server drops `note` only because its
+schema is not `.strict()`. Nothing was validated away on this side: pass the
+object the contract declares, not a wider one it happens to contain.
 
 Contract metadata describes an effect; it does not authorize one. Authentication,
 scope and destination policy remain in the application/server boundary. A schema
@@ -9541,6 +9594,67 @@ makes one thing your job rather than the resolver's:
 The mechanical part is identical either way. Only the *noticing* differs, and an
 exact pin moves it onto you.
 
+## Released migration: 0.74.0
+
+One change, and it only reaches you if you catch a refusal the **client** raised — one it made while
+planning the request, before anything was sent. A server refusal is unchanged.
+
+### If you match on the text of a client-side refusal
+
+A missing path param, a missing scoped prefix key, a non-flat field in a `GET` input, a missing or
+invalid multipart file: each used to arrive as a plain `Error` carrying only a sentence. They now
+arrive as an `ApiError` in the same shape a server validation failure uses.
+
+```ts
+// before
+catch (e) {
+  if (/Missing path param/.test(e.message)) …
+}
+
+// after
+catch (e) {
+  if (e.code === 'VALIDATION_ERROR' && e.status === 0) …   // refused here, nothing was sent
+}
+// e.details.issues[0].path === 'id'
+```
+
+`status` is what separates the two worlds, and it is not new — `0` has always meant *this never
+reached the server*, as `REQUEST_ABORTED` and `REQUEST_TIMEOUT` already used it:
+
+| | `code` | `status` |
+|---|---|---|
+| the client refused your arguments | `VALIDATION_ERROR` | `0` |
+| the server refused your arguments | `VALIDATION_ERROR` | `400` |
+
+`details.issues` is the same `{ path, code, message }` array on both, so one rendering serves both —
+and `zodIssues` / `ZodIssueSummary` are now importable from `stitchkit` itself, not only from
+`stitchkit/server`.
+
+### If you are on `createHttpClient` and your call site relied on a synchronous throw
+
+This is the sharp one, because it is invisible in a diff. Those refusals used to be thrown
+**synchronously** on the Ky-backed client — before the call returned a promise — so
+`api.upload({}).catch(handler)` never reached the handler, while the same mistake on the bare-fetch
+client rejected normally. They now reject on both.
+
+```ts
+// before, on createHttpClient only
+try {
+  api.upload({})            // threw here
+} catch (e) { … }
+
+// after, on both transports
+await api.upload({}).catch(handler)
+```
+
+A `try/catch` around an `await`ed call keeps working. A `try/catch` around an un-awaited call no
+longer catches anything — which was already true on the other transport.
+
+Not a migration, but worth knowing: a missing multipart file used to be reported as
+`UNKNOWN_ERROR`, the code that means *this client cannot tell you what happened*, on the one refusal
+where it is certain nothing was sent. → ADR 0148 carries the reasoning, including why argument
+validation stays on the server.
+
 ## Released migration: 0.73.0
 
 Two breaking changes. Nothing you send to a server changed, and only one of these
@@ -9588,6 +9702,25 @@ Match `err.code` instead: it is the contract, and it did not change. An error
 carrying a real message is untouched. An empty message now counts as no message,
 for the same reason — an empty string is not an explanation either.
 
+### If a diagnostic journal lock file is already on disk
+
+One operator step, and only on a host that has been **renamed** since its lock was written.
+
+A lock written before this version carries no machine identity, so there is nothing to compare and
+the host name is all that is left. If the name still matches, the lock reclaims exactly as it always
+did and there is nothing to do. If the name has changed, the lock is `unattributable` and is refused
+— the same refusal this release exists to end, except that this particular file predates the fix and
+cannot be repaired from the inside. Delete it once:
+
+```sh
+rm <journal path>.lock   # only when the host was renamed since the file was written
+```
+
+Locks written from this version on carry the machine identity, so the situation cannot recur. To see
+which case you are in without guessing, read the refusal instead of the file:
+`readDiagnosticJournalLockDiagnosis(err)` returns `attribution: 'unattributable'` for exactly this
+one, and `'another-machine'` for a lock that genuinely belongs elsewhere and must **not** be deleted.
+
 Two related fixes need no migration, but change what you will see. An error the
 transport raised through `createHttpClient` now carries the transport's own text
 in `message` and the original error as `cause`, where before it carried neither
@@ -12338,6 +12471,9 @@ The browser-and-server entrypoint. Re-exports everything from
 | `PathPrefixArgs` | _type_ | required string-valued keys exposed to a typed dynamic `pathPrefix` callback |
 | `createHttpClient` | function | the Ky-based HTTP transport; on Next.js SSR its first attempt stays request-memoizable while every retry is a distinct transport attempt — [guide](../guide/client.md#createhttpclient) |
 | `ApiError` | class | a non-2xx or client failure, with `code` / `status` / `details` / `hint`, optional readonly `traceId` from `x-request-id`, and standard `cause` preserving an injected transport failure |
+| `zodIssues` | function | a `ZodError` → structured `{ path, code, message }[]` — the exact projection a `VALIDATION_ERROR` carries in `ApiError.details.issues`, so a caller renders one shape. Also on `stitchkit/server`; same name, one definition |
+| `ZodIssueSummary` | _type_ | one structured validation issue (`{ path, code, message }`) — the element type of `details.issues`. Also on `stitchkit/server` |
+| `formatZodError` | function | a `ZodError` → a readable, field-summarised string. Also on `stitchkit/server` |
 | `HttpClient` | _type_ | the transport interface `createClient` builds on |
 | `ConfiguredHttpClient` | _type_ | a framework-created `HttpClient` carrying its readonly `baseUrl` for URL builders |
 | `HttpClientConfig` | _type_ | config for `createHttpClient`; retry `limit` counts retries after the initial attempt (default 2 = at most 3 GET attempts), with `statusCodes: []` by default; `fetch` installs an explicit transport and is mutually exclusive with the legacy Bun-only `unix` option — [details](../guide/client.md#createhttpclient) |

package/package.json

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