stitchkit 0.72.5 → 0.74.0

package/dist/remote.js

@@ -1,7 +1,7 @@
 import {
   ApiError,
   createClient
-} from "./index-6d32zk83.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-6d32zk83.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 17 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 17 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` |
 
@@ -2005,6 +2005,18 @@ proves that the remote operation did not begin; Stitchkit never silently retries
 an ambiguous write. Response consumption/cancellation belongs to the operation,
 and `close()` interrupts active work and destroys owned connections.
 
+**A caller's cancellation reaches the server on both lanes.** The transport picks
+a raw-socket lane under Bun and `node:http` elsewhere, and both propagate
+`AbortSignal` the same way: aborting the request tears the connection down, and
+the handler's `ctx.signal` fires — measured at roughly 300 ms for a 200 ms abort
+over either lane, matching plain TCP. `close()` is a different thing: it ends the
+*transport*, not one request, and a request-level abort does not close it.
+
+The one way to see cancellation appear not to work is to pass the signal to the
+plain callable — `api.thing(args, { signal })` — where options are ignored in
+silence. See [per-call cancellation](#per-call-cancellation): `withOptions` is the
+only door.
+
 The response total is a unary-body policy, not a stream-buffer measurement. A
 long-lived NDJSON/SSE client opts into streaming explicitly instead of choosing
 an arbitrarily large integer:
@@ -2078,6 +2090,62 @@ including an explicitly declared empty `200` or `205`. A missing body for a
 declared output, or a body for an endpoint with no output, fails loudly instead
 of changing the typed result.
 
+Validation runs in one direction. The response is checked against the endpoint's
+`output` schema before it reaches the caller; arguments are **not** checked
+against `input` or `params` before the request is sent. A value the contract
+forbids travels to the server and comes back as a `VALIDATION_ERROR` — `400`,
+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.
+
+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
+// 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
+```
+
+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 it means a
+local check passes traffic the server will reject, which is the opposite of what
+it was added for.
+
+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
 `Response`, giving the caller direct access to status and headers without JSON
@@ -2115,11 +2183,22 @@ mistaking their callback context for Stitchkit transport options.
 argument is ignored, in silence, and the request runs to completion while the
 caller believes it was cancelled or bounded. TypeScript refuses the extra
 argument at a typed call site and says nothing at an untyped one, which is where
-the mistake actually happens. Nothing can catch it at runtime either: probing the
-second argument is exactly what the callback safety above forbids, since reading
-a foreign object's `signal` may execute someone else's getter. So the rule is
-simply this — **per-call options only ever go through `withOptions`**, and a
-cancellation that appears to do nothing is the first thing to check.
+the mistake actually happens. Nothing can catch it at runtime **on the bare
+callable**: probing its second argument is exactly what the callback safety above
+forbids, since reading a foreign object's `signal` may execute someone else's
+getter. So the rule is simply this — **per-call options only ever go through
+`withOptions`**, and a cancellation that appears to do nothing is the first thing
+to check.
+
+`withOptions` itself is guarded, because there the count settles it without
+reading anything. Its arity depends on the endpoint — one argument when there is
+no contract input, two when there is — and a call carrying more throws a
+`TypeError` naming the endpoint and the correct shape. That guard exists because
+the silent version of this mistake is expensive: the options are dropped, the
+request goes out uncancelled, the caller still receives `REQUEST_ABORTED`
+(cancellation is decided from the signal it was handed, not from what the
+transport did), and the server runs the operation to its own deadline. Every
+symptom then points at the transport, and the investigation goes there.
 
 ```ts
 const controller = new AbortController()
@@ -2139,10 +2218,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.
@@ -2186,9 +2275,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
@@ -9496,6 +9592,143 @@ 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
+can reach a call site the compiler already checks.
+
+### If you call `withOptions` from a call site that lost its types
+
+`withOptions` takes one argument on an endpoint with no contract input, two when
+there is one. Passing two to a no-input endpoint used to succeed and silently
+drop the options: the request went out **uncancelled**, the caller still received
+`REQUEST_ABORTED` — cancellation is decided from the signal it was handed, not
+from what the transport did — and the server ran the operation to its own
+deadline. Every symptom then points at the transport, and the investigation goes
+there. It now throws a `TypeError` naming the endpoint and the correct shape.
+
+```ts
+// before — the options were dropped and the request was never cancelled
+api.ping.withOptions({}, { signal })
+
+// after
+api.ping.withOptions({ signal })
+```
+
+A typed call site already refused the wrong arity, so this reaches only code that
+does not have the types: a `Record<string, …>` view of the client, a hand-written
+double, a dynamic dispatch. The guard counts arguments and never reads them, so a
+method handed to a callback API behaves exactly as before.
+
+### If you match on `ApiError.message`
+
+An `ApiError` that nothing explained used to carry `API Error: ${code}` — a
+string that reads like an explanation while only restating the code, so a caller
+could not tell an origin that explained a failure from one that said nothing. It
+now says which it is.
+
+```ts
+// before
+err.message === 'API Error: INVALID_INPUT'
+
+// after
+err.message === 'INVALID_INPUT (no message supplied)'   // better: match err.code
+```
+
+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
+and filed the text under `details.message` alone; if you followed the retry rule
+in [the client guide](./client.md) — inspect the adapter's `cause`, retry only
+when it proves dispatch did not happen — that rule was not executable on this
+transport and now is. And the client guide now states which direction validation
+runs: responses are checked against `output`, arguments are **not** checked
+before being sent.
+
 ## Released migration: 0.72.0
 
 Nothing you *pass* changed. Both items are about types you read or build, and
@@ -12236,6 +12469,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) |
@@ -12760,6 +12996,7 @@ cutovers are covered by the executable
 | `DiagnosticJournalConfig` / `DiagnosticJournal` | _type_ | owner schema/path/limits/failure observer and the synchronous `submit`, bounded-wait `flush`/`close`, status handle |
 | `DiagnosticJournalLimitsSchema` / `DiagnosticJournalLimits` | schema / _type_ | positive event, pending-item, pending-byte, file-byte and retained-file limits |
 | `DiagnosticJournalLockPolicySchema` / `DiagnosticJournalLockPolicy` | schema / _type_ | `refuse` (default) or `reclaim-stale`, which reclaims only a lock whose recorded owner is provably gone |
+| `readDiagnosticJournalLockDiagnosis` / `DiagnosticJournalLockDiagnosis` | function / _type_ | why a `reclaim-stale` acquisition refused — owner alive, another machine, or a lock this host cannot attribute — read off the thrown `EEXIST` |
 | `DiagnosticJournalSubmitResultSchema` / `DiagnosticJournalSubmitResult` | schema / _type_ | accepted epoch/sequence or explicit invalid, oversized, capacity, closed or failed refusal |
 | `DiagnosticJournalStatusSchema` / `DiagnosticJournalStatus` | schema / _type_ | state, limits, exact admission/write/failure counters, pending ownership, rotations, partial tails and last safe sequences |
 | `DiagnosticJournalFrameSchema` / `DiagnosticJournalFrame` | schema / _type_ | version-1 JSONL frame carrying process epoch, contiguous accepted sequence and schema-validated JSON event |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "stitchkit",
-  "version": "0.72.5",
+  "version": "0.74.0",
   "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",