stitchkit 0.42.0 → 0.43.1

package/llms-full.txt

@@ -44,7 +44,7 @@ keeping server-only code (`Bun.serve`, the MCP SDK) out of browser bundles.
 | `stitchkit/node` | server (Node ≥ 22) | `serveNode` + the runtime-agnostic core — the Node mirror of `/server` |
 | `stitchkit/tools` | server | `createMcpHandler`, `mountMcp`, `mountAgent`, the OAuth provider, native tools |
 | `stitchkit/cli` | server | `createCli` — the CLI transport, light (no MCP SDK / `ai`) |
-| `stitchkit/observability` | server | the audit layer — `createAuditHook`, trace context, sanitisation |
+| `stitchkit/observability` | server | request/tool event projections — `createObservability`, trace context, sanitisation |
 | `stitchkit/react` | browser | `createCursorQuery`, `createCacheBridge` |
 
 Rule of thumb: browser code imports `stitchkit` and `stitchkit/react`; server
@@ -168,7 +168,9 @@ actionable error naming the package and the install command — not a bare
 - [Testing & deployment](./testing-and-deployment.md).
 - [API reference](../api/reference.md) — every export, by entrypoint.
 
-A complete runnable app is in [`packages/starter`](../../packages/starter).
+For a complete production-shaped app, run `bun create stitchkit my-app`. The
+canonical generated topology is maintained in
+[`packages/create-stitchkit/template`](../../packages/create-stitchkit/template).
 
 
 ==============================================================================
@@ -339,6 +341,19 @@ tools. Narrow it with `expose`:
 - `expose: ['MCP', 'AGENT']` — a tool only; no HTTP route.
 - omit `expose` — all transports.
 
+For a curated or security-sensitive tool surface, opt into explicit tool
+exposure at the scoped factory:
+
+```ts
+const { defineContract } = createContractFactory<AppScope>({
+  toolExposure: 'explicit',
+})
+```
+
+With this policy, omitting `expose` materializes `['HTTP']` on the returned
+endpoint. MCP, Agent and CLI then require an explicit endpoint array. The plain
+factory and `defineContract` keep the default-on behaviour above.
+
 Tool transports (`MCP`, `AGENT`) skip three kinds of endpoint automatically:
 `multipart` (a file upload is not a tool call) and
 [`rawResponse`](./server.md#raw-response-endpoints) (its answer is bytes, which
@@ -542,9 +557,11 @@ export const { defineContract } = createContractFactory<'public' | 'user' | 'adm
 export const users = defineContract({ prefix: 'users', scope: 'user' }, { … })
 ```
 
-The vocabulary is yours; each returned `ContractDef` retains its concrete scope
-literal, so scope-aware registries select the exact config without another
-wrapper.
+The vocabulary is yours; each returned `ScopedContractDef` retains its concrete
+scope literal as a required `meta.scope` field, so scope-aware registries select
+the exact config without `NonNullable` or another wrapper. Plain `ContractDef`
+keeps optional scope because ordinary `defineContract` still supports its
+default-public overload.
 
 ## One source of truth
 
@@ -1529,10 +1546,16 @@ try {
     err.message  // 'Note not found'
     err.details  // structured details, if any
     err.hint     // optional hint
+    err.traceId  // x-request-id — correlate this failure with backend logs
   }
 }
 ```
 
+`traceId` is present when the server returned `x-request-id`. A network error,
+timeout or abort without an HTTP response cannot carry one. Cross-origin
+browser code can read it through Stitchkit's default CORS expose list; a custom
+`cors.exposeHeaders` policy must keep `x-request-id` exposed.
+
 The error model is shared with the server — see [Auth & errors](./auth-and-errors.md).
 
 ## Auth events
@@ -1664,6 +1687,11 @@ The server side is [`streamSSE`](./server.md#sse-streaming).
 
 # MCP & AI agents
 
+The application generated by `bun create stitchkit` includes a working
+stateless MCP endpoint and a separate `bun run tools` manifest command. Both
+are assembled from the same implemented project contracts as HTTP and CLI, so
+the generated project is the canonical end-to-end example for this chapter.
+
 The same contract that drives the HTTP API also drives AI tooling. An endpoint
 exposed on `MCP` becomes a [Model Context Protocol](https://modelcontextprotocol.io)
 tool — callable from Claude, Cursor and other MCP clients. An endpoint exposed on
@@ -1978,8 +2006,14 @@ as one thing. Where they agree, that is what you get; where they disagree — a
 `.refine()` only one of them carries, two different bounds on the same number, an
 enum against a free string — the *constraint* is dropped and the **type** is not.
 A field that is a number in every variant is advertised as a number, not as a
-bare description. Only genuinely different kinds (a string in one variant, a
-number in another) fall back to unconstrained. → ADR 0044
+bare description. When the kinds genuinely differ, the flat projection keeps
+every provable kind in a deterministic JSON Schema type array — for example
+`type: ['string', 'array']` — while dropping constraints that are not sound for
+all branches. Nested `oneOf` / `anyOf` values still contribute their provable
+base kinds without reintroducing union keywords. Only a branch whose kind is
+actually unknowable, such as a free-form schema or unresolved reference, leaves
+the collision unconstrained. → ADRs [0044](../decisions/0044-a-collided-field-keeps-its-type.md)
+and [0065](../decisions/0065-flat-collisions-preserve-every-known-kind.md)
 
 It is **deep** because the projection walks the generated JSON Schema document,
 including objects, arrays, tuples and schema-definition nodes. Structurally
@@ -1987,6 +2021,10 @@ identifiable discriminated object unions are flattened wherever they occur.
 Plain unions and unions hidden behind unresolved external references remain
 unions because Stitchkit cannot soundly invent a discriminator.
 
+Use the default `flattenUnionInput: false` when the model must see the exact
+relationship between a discriminator and each branch. The flat type array is a
+sound set of possible JSON kinds, not a reconstruction of those correlations.
+
 The flattened form is **lossy but never executable**. Per-variant refinements
 and incompatible constraints are widened in the presentation document; the
 original Zod contract enforces them exactly once inside `executeToolMethod`.
@@ -2287,6 +2325,33 @@ const agentTools = mountAgent([service], {
 })
 ```
 
+When several runtime tools share application context and identity, bind both
+once with `createRuntimeToolFactory`. Its Zod context schema is parsed once per
+call inside the same runner; the authored handler receives validated context and
+parsed `input`, while lifecycle, hooks, output validation and presenters remain
+unchanged:
+
+```ts
+const knowledgeTools = createRuntimeToolFactory({
+  serviceName: 'agentKnowledge',
+  scope: 'user',
+  context: z.object({ userId: z.string(), tz: z.string() }),
+})
+
+const countRecords = knowledgeTools.define({
+  name: 'count_records',
+  action: 'countRecords',
+  method: 'GET',
+  description: 'Count records',
+  input: z.object({ kind: z.string() }),
+  output: z.object({ count: z.number() }),
+  handler: async ({ userId, tz, input }) => countFor(userId, tz, input.kind),
+})
+```
+
+`serviceName` and `scope` cannot be overridden by one definition. Use standalone
+`defineRuntimeTool` when tools do not share a context schema or identity.
+
 `transports` defaults to `['MCP', 'AGENT']`; set an explicit subset when an
 operation belongs on only one surface. The configured identity becomes the
 hook/lifecycle `OperationIdentity` and the tool `RequestEvent`
@@ -3283,8 +3348,9 @@ Use the exported `zodIssues(error)` to build the same structured list from a
 ### On the client
 
 The client parses that envelope back into an `ApiError` with the same `code`,
-`status`, `details` and `hint` — see [Typed client → ApiError](./client.md#apierror).
-The error round-trips: one model, server to client.
+`status`, `details` and `hint`, plus the response `x-request-id` as optional
+readonly `traceId` — see [Typed client → ApiError](./client.md#apierror). The
+error round-trips without adding correlation data to the response body.
 
 ### Stitch codes vs your codes
 
@@ -3443,10 +3509,10 @@ stitchkit answers this at two levels.
 - **The raw hooks** — `LifecycleHooks` and `ToolCallHooks`. Every request and
   every tool call passes through a point you can observe. The lowest level;
   always available. [Jump ↓](#the-raw-hooks)
-- **`stitchkit/observability`** — the audit layer built on those hooks: W3C
-  trace context, an `AsyncLocalStorage` request context, payload sanitisation,
-  and `createAuditHook` to wire it all into one sink. Your logging becomes a
-  table plus a `write` function. [Start here ↓](#the-observability-module)
+- **`stitchkit/observability`** — framework-owned HTTP completion plus canonical
+  tool hooks: W3C trace context, an `AsyncLocalStorage` request context, payload
+  sanitisation and `createObservability` with independent request/tool sinks.
+  [Start here ↓](#the-observability-module)
 
 stitchkit still ships no logger and no audit store — those are the app's choice.
 What it ships is the machinery that turns a completed call into a clean,
@@ -3455,52 +3521,55 @@ normalised record.
 ## The observability module
 
 `stitchkit/observability` is server-only. It has three parts — a trace context,
-a request context, and the audit hook — and you usually touch only the last.
-
-### createAuditHook
-
-`createAuditHook` is the whole module in one call. You give it a `write` sink;
-it gives you back a wrapper for each surface. Every completed call — HTTP
-request, MCP tool call, agent tool call — is normalised into one `RequestEvent`
-and handed to `write`.
-
-```ts
-import { createAuditHook } from 'stitchkit/observability'
-
-export const audit = createAuditHook({
-  // The only thing the app supplies — persist one row.
-  write: (event) => {
-    db.auditLog.create({ data: {
-      traceId:    event.traceId,
-      source:     event.source,      // 'http' | 'mcp' | 'agent'
-      method:     event.method,      // verb, or 'TOOL'
-      path:       event.path,
-      ok:         event.ok,
-      statusCode: event.statusCode,
-      durationMs: event.durationMs,
-      userId:     event.userId,
-      payload:    event.payload,     // already sanitised
-    }})
+a request context, and event projections — and you usually touch only the last.
+
+### createObservability
+
+`createObservability` configures request and tool projections independently.
+Every completed call is normalised into one `RequestEvent`; HTTP completion is
+owned directly by `createHandler`, while MCP/Agent completion uses the canonical
+`ToolCallHooks` runner. There is no nested HTTP audit wrapper.
+
+```ts
+import { createObservability } from 'stitchkit/observability'
+
+const write = (event) => db.auditLog.create({ data: {
+  traceId: event.traceId,
+  source: event.source,
+  method: event.method,
+  path: event.path,
+  ok: event.ok,
+  statusCode: event.statusCode,
+  durationMs: event.durationMs,
+  userId: event.userId,
+  payload: event.payload,
+}})
+
+export const observability = createObservability({
+  request: {
+    write,
+    includePayload: false, // default: no Request.clone(), payload is null
+    filter: (event) => event.method !== 'GET',
+  },
+  tools: {
+    write,
+    filter: (event) => event.source === 'mcp' || event.source === 'agent',
   },
-  // Optional — keep only the events you care about.
-  filter: (event) => event.source !== 'http' || event.method !== 'GET',
 })
 ```
 
-It returns an [`AuditHook`](#audithook) — `{ http, toolCall }`:
+Wire each projection where its completion is owned:
 
 ```ts
-// HTTP — wrap the fetch handler, inside wrapInRequestContext.
-Bun.serve({ fetch: wrapInRequestContext(audit.http(handler)) })
+createServer({ services, observability: observability.request })
 
-// MCP & agents — pass as the tool-call hooks.
-createMcpHandler({ /* … */ hooks: audit.toolCall })
-mountAgent(service, { hooks: audit.toolCall })
+createMcpHandler({ /* … */ hooks: observability.toolCall })
+mountAgent(service, { hooks: observability.toolCall })
 ```
 
-One `createAuditHook`, one sink, every surface. The sink runs
-fire-and-forget and its errors are swallowed — a slow or failing audit write
-can never block or break the request it observes.
+Each sink runs fire-and-forget and fails independently: a slow or broken request
+sink cannot block the response, suppress operational logging or break the tool
+sink.
 
 ### RequestEvent
 
@@ -3519,32 +3588,26 @@ queryable across all three:
 | `ok` / `statusCode` | outcome — real HTTP status, or `200`/`400` for a tool |
 | `durationMs` / `startedAt` | timing |
 | `errorCode` / `errorMessage` / `errorDetail` | failures only — `errorDetail` carries the structure the message flattens (e.g. Zod issues) |
-| `payload` | the request body / tool arguments — sanitised |
+| `payload` | sanitised tool arguments; HTTP is `null` unless request `includePayload` is enabled |
 | `resultSize` / `responseBytes` | result item count + serialised size |
 | `userId` / `ipAddress` / `userAgent` | identity |
 
 ### Request context
 
-`createAuditHook`'s `http` wrapper reads a request context — trace ids, timing,
-identity — from `AsyncLocalStorage`. `wrapInRequestContext` establishes it, and
-must be the **outermost** wrapper of your fetch handler:
+When request observability is configured, `createHandler` establishes the
+`AsyncLocalStorage` request context itself and uses the same completion snapshot
+for operational logging and `RequestEvent`. No `wrapFetch` composition is
+needed:
 
 ```ts
-import { getTraceId, wrapInRequestContext } from 'stitchkit/observability'
-
-Bun.serve({
-  fetch: wrapInRequestContext(audit.http(handler)),
-})
+createServer({ services, logging, observability: observability.request })
 ```
 
-`createServer` and `serveNode` build their own `fetch`, so compose through
-**`wrapFetch`** instead — same order, the context outermost:
+`wrapInRequestContext` remains available for a custom fetch pipeline that does
+not use `createHandler`; it is no longer part of built-in HTTP audit wiring:
 
 ```ts
-createServer({
-  services,
-  wrapFetch: (fetch) => wrapInRequestContext(audit.http(fetch)),
-})
+Bun.serve({ fetch: wrapInRequestContext(customFetch) })
 ```
 
 Some fields are filled in late. Set them from the hooks that know:
@@ -3645,7 +3708,8 @@ locally; you do not need to change `NODE_ENV` or deploy.
 Every response the stitchkit handler produces carries the resolved id as
 **`x-request-id`**. With `cors` configured it is in the default
 `Access-Control-Expose-Headers`, so a browser client can read it and quote it in
-a bug report. Note the deliberate asymmetry: inbound the id may arrive as
+a bug report. Stitchkit browser clients retain it as `ApiError.traceId` on
+response-backed failures. Note the deliberate asymmetry: inbound the id may arrive as
 `X-Trace-Id` *or* `X-Request-Id`; outbound there is one name and no alias.
 
 Log the same id from nginx and the two logs join on one key. `log_format` and
@@ -3679,8 +3743,8 @@ every tool call underneath it. With no inbound header a fresh root trace is
 minted. Each tool call opens a [`childSpan`](#trace-context) of the request it
 runs in.
 
-You rarely call the trace functions directly — `wrapInRequestContext` and
-`createAuditHook` use them for you. They are exported (`resolveTraceContext`,
+You rarely call the trace functions directly — `createHandler` request
+observability and `wrapInRequestContext` use them for you. They are exported (`resolveTraceContext`,
 `parseTraceparent`, `formatTraceparent`, `childSpan`) for when you need to
 propagate a `traceparent` onward to another service.
 
@@ -3715,12 +3779,19 @@ A payload goes into an audit row only after `sanitizePayload`:
   never the bytes;
 - the result is **capped** — anything over the byte limit becomes a preview.
 
-`createAuditHook` runs it on every event; tune it through `sanitize`:
+`createObservability` runs it on every emitted event; tune each sink separately:
 
 ```ts
-createAuditHook({
-  write,
-  sanitize: { maxBytes: 8_000, sensitiveKeys: /password|token|pin/i },
+createObservability({
+  request: {
+    write,
+    includePayload: true,
+    sanitize: { maxBytes: 8_000, sensitiveKeys: /password|token|pin/i },
+  },
+  tools: {
+    write,
+    sanitize: { maxBytes: 8_000, sensitiveKeys: /password|token|pin/i },
+  },
 })
 ```
 
@@ -3729,7 +3800,7 @@ need to sanitise something outside the audit path.
 
 ## The raw hooks
 
-`createAuditHook` is built on hooks you can also use directly — for a one-off
+Tool observability is built on hooks you can also use directly — for a one-off
 metric, a custom log line, anything that is not a full audit row.
 
 | Surface | Hook | Fires |
@@ -3803,7 +3874,7 @@ observe. (This is also why it lives on `ToolCallHooks` rather than being an
 object must stay assignable to `ToolLifecycle`.)
 
 **Do not reach for `setRequestError` here.** It writes to the *request* context,
-which `createAuditHook`'s **tool** row does not read: a tool event takes
+which the built-in **tool** row does not read: a tool event takes
 `errorCode` / `errorMessage` / `errorDetail` from the `ToolResult`, and only
 identity and `dimensions` from the context. Calling it in `onToolError` would
 leave the tool row exactly as scrubbed as before. It is right for the **HTTP**
@@ -3829,7 +3900,7 @@ validation failure or a `beforeToolCall` rejection leaves it `undefined`, becaus
 neither ever had a raw value to lose. Consumers destructure only the fields they
 use; future optional fields do not change callback arity.
 
-`createAuditHook` uses it already. Where the envelope was scrubbed to
+`createObservability({ tools })` uses it already. Where the envelope was scrubbed to
 `INTERNAL_SERVER_ERROR`, the row's `errorMessage` becomes the real message
 instead of the placeholder; a truthful envelope (a thrown `AppError`, a
 `ZodError`) is left alone, `errorCode` and `errorDetail` are untouched, and the
@@ -3842,7 +3913,7 @@ sink of your own (a tracker, a stack, an alert), `afterToolCall` for the record.
 
 ### Keying a row on (service, action)
 
-`createAuditHook` already keys every event by **service** and **action**
+Built-in observability keys every event by **service** and **action**
 (`event.serviceName` / `event.action`, → ADR 0029) — reach for the raw hook only
 when you also need the handler **output**, which the audit wrapper never sees. For
 that, read the endpoint identity off the `OperationIdentity` the tool hook
@@ -3870,11 +3941,11 @@ hooks: {
 }
 ```
 
-> **Why the HTTP audit is a wrapper, not a lifecycle hook.** `LifecycleHooks`
-> has a single `onError` — an audit built on it would compete with the app's own
-> error handler. `createAuditHook`'s `http` wrapper sees the final `Response`
-> instead, success and error alike, and never contends for a hook. The raw
-> lifecycle hooks remain yours for everything else.
+> **Why HTTP observability is framework-owned, not a lifecycle hook.**
+> `LifecycleHooks` has a single `onError`; an audit built on it would compete
+> with the app's error renderer and miss raw/unmatched exits. `createHandler`
+> sees the final response on every path and emits one completion without
+> consuming an application hook.
 
 Keep any sink **asynchronous and self-contained**: a slow or failing write must
 never block or break the request. Swallow the sink's own errors.
@@ -4023,7 +4094,8 @@ Notes for a Node host:
 stitchkit serves the API. A SPA front-end is built and hosted separately — a
 static host or CDN in production, its own dev server in development. The backend
 does not serve static files (`staticRoute` exists for the occasional asset, not
-a whole app). See [`packages/starter`](../../packages/starter) for the split.
+a whole app). `bun create stitchkit my-app` demonstrates the supported split:
+an independently built Next.js frontend and Bun/Stitchkit API.
 
 ### MCP
 
@@ -4160,6 +4232,76 @@ rule read it the same way on both surfaces — one contract, every surface, no
 per-transport tenant plumbing.
 
 
+==============================================================================
+# Guide: Frontend integrations  (docs/guide/frontend-integrations.md)
+==============================================================================
+
+---
+title: Frontend integrations
+description: Compose Stitchkit with Next.js, React Router or a separate Vite development server
+type: architecture
+status: active
+created: 2026-08-08
+updated: 2026-08-08
+---
+
+# Frontend integrations
+
+The official `bun create stitchkit` application uses Next.js with a separate
+Bun API. Stitchkit remains a Fetch-native backend and does not own frontend
+routing, SSR or HMR.
+
+## Theme boundary in the official starter
+
+The generated Next.js application uses `@wrksz/themes`, not a Stitchkit-owned
+theme abstraction. Its root `ThemeProvider` comes from `@wrksz/themes/next` and
+lives directly in the server layout so Next 16 can inject the first-paint script
+through `useServerInsertedHTML`. The default `hybrid` storage reads a cookie
+during SSR and mirrors changes to localStorage for cross-tab synchronization.
+
+Client components import typed hooks from the fine-grained
+`@wrksz/themes/client/*` entrypoints. Nested visual examples use
+`ClientThemeProvider` with a scoped target and `storage="none"`; they never
+become a second global provider. Applications may add account-backed theme
+preferences, CSP nonces or consent-aware storage, but those policies remain
+application concerns.
+
+Theme state and theme animation are intentionally separate. `@wrksz/themes`
+owns selection, resolution, SSR prepaint and persistence. The generated app's
+`theme/transition.ts` wraps an interactive `setTheme` call with the native View
+Transition API and exposes typed style, duration, easing and origin settings.
+The default 250 ms crossfade matches the starter's visual language; the
+catalogue also demonstrates a radial reveal. The runner bypasses animation when
+the browser lacks the API or `prefers-reduced-motion: reduce` is active.
+
+## React Router
+
+Mount a `createHandler()` result in a catch-all resource route and pass the
+incoming `Request` through unchanged. Mount MCP as a second resource route. An
+SSR request creates its own typed client using that request's origin and auth;
+do not share request identity in a module singleton.
+
+```ts
+export async function loader({ request }: LoaderFunctionArgs) {
+  return apiHandler(request);
+}
+
+export async function action({ request }: ActionFunctionArgs) {
+  return apiHandler(request);
+}
+```
+
+## Vite
+
+Run Vite and the Stitchkit API as separate development processes. Declare one
+proxy for `/api`, `/mcp` and `/socket.io`; browser code still calls the typed
+client with same-origin paths. Production serves the static Vite output from a
+static host or reverse proxy and routes those backend paths to Stitchkit.
+
+Do not duplicate DTOs or handwritten API wrappers in either integration. The
+shared contract remains the only transport schema source.
+
+
 ==============================================================================
 # Guide: Upgrading  (docs/guide/upgrading.md)
 ==============================================================================
@@ -4228,6 +4370,32 @@ current one *up to* your target, and apply each snippet.
 
 ## Unreleased breaking migrations
 
+HTTP observability now completes inside the framework handler instead of a
+nested fetch wrapper. Configure request and tool sinks explicitly:
+
+```ts
+// before
+const audit = createAuditHook({ write })
+createServer({
+  services,
+  wrapFetch: (handler) => wrapInRequestContext(audit.http(handler)),
+})
+mountAgent(services, { hooks: audit.toolCall })
+
+// after
+const observability = createObservability({
+  request: { write, includePayload: true },
+  tools: { write },
+})
+createServer({ services, observability: observability.request })
+mountAgent(services, { hooks: observability.toolCall })
+```
+
+Body capture changed from always-on for body methods to opt-in. Set
+`includePayload: true` only when the request sink needs the sanitized JSON body.
+There is no `createAuditHook` or `audit.http` compatibility path;
+`wrapInRequestContext` remains only for custom fetch pipelines.
+
 Tool introspection now accepts one object-shaped contract/runtime surface. Stop
 calling the internal contract collector or merging a locally converted runtime
 manifest:
@@ -4679,7 +4847,7 @@ The browser-and-server entrypoint. Re-exports everything from
 | `contractEndpointMatchers` | function | compile exact pathname matchers for selected HTTP contract operations and expected-401 policy |
 | `PathPrefixArgs` | _type_ | required string-valued keys exposed to a typed dynamic `pathPrefix` callback |
 | `createHttpClient` | function | the Ky-based HTTP transport — [guide](../guide/client.md#createhttpclient) |
-| `ApiError` | class | a non-2xx response, with `code` / `status` / `details` / `hint` |
+| `ApiError` | class | a non-2xx response, with `code` / `status` / `details` / `hint` and optional readonly `traceId` from `x-request-id` |
 | `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` |
@@ -4729,6 +4897,11 @@ from the root `stitchkit`.
 |--------|------|---------|
 | `defineContract` | function | declare a contract — [guide](../guide/contracts.md#definecontract) |
 | `createContractFactory` | function | a `defineContract` with a required allowed scope that retains each concrete literal — [guide](../guide/contracts.md#scope) |
+| `ContractFactoryConfig` | _type_ | optional scoped-factory policy, including explicit tool exposure |
+| `ContractFactoryToolExposure` | _type_ | `'explicit'` — omitted endpoint exposure materializes as HTTP-only |
+| `ExplicitScopedDefineContract` | _type_ | scoped factory authoring with explicit tool opt-in |
+| `ExplicitToolExposureEndpoints` | _type_ | endpoint map after missing exposure is materialized as `['HTTP']` |
+| `ScopedContractDef` | _type_ | a factory-defined contract whose `meta.scope` is the required concrete literal |
 | `ScopedDefineContract` | _type_ | the `defineContract` `createContractFactory` returns |
 | `ALL_TRANSPORTS` | constant | `['HTTP', 'MCP', 'AGENT', 'CLI']` |
 | `ContractDef` | _type_ | a defined contract |
@@ -4939,14 +5112,18 @@ Server-only. The audit layer one level above the raw hooks — W3C trace context
 an `AsyncLocalStorage` request context, payload sanitisation and a normalised
 audit event. See the [Observability guide](../guide/observability.md).
 
-### Audit
+### Events
 
 | Export | Kind | Summary |
 |--------|------|---------|
-| `createAuditHook` | function | wire both surfaces into one sink — [guide](../guide/observability.md#createaudithook) |
+| `createObservability` | function | configure framework-owned request completion and canonical tool event sinks — [guide](../guide/observability.md#createobservability) |
 | `RequestEvent` | _type_ | the normalised audit event handed to the sink |
-| `AuditConfig` | _type_ | config for `createAuditHook` |
-| `AuditHook` | _type_ | the `{ http, toolCall }` the hook returns |
+| `ObservabilityConfig` | _type_ | independent request and tool sink configuration |
+| `Observability` | _type_ | the `{ request?, toolCall }` wiring result |
+| `RequestEventSinkConfig` | _type_ | `write`, `filter` and sanitisation for one event surface |
+| `RequestObservabilityConfig` | _type_ | request sink plus opt-in payload capture |
+| `HttpRequestCompletion` | _type_ | the single framework-owned HTTP outcome projected to logging and request events |
+| `HttpRequestObserver` | _type_ | server-facing projection consumed by `HandlerConfig.observability` |
 
 ### Request context
 
@@ -5003,6 +5180,7 @@ Server-only. Turns contracts into MCP and AI-agent tools. Needs the
 | `implementRemote` | function | bind a contract to a remote HTTP API — [guide](../guide/mcp-and-agents.md#proxying-a-remote-api--implementremote) |
 | `mountAgent` | function | a Vercel AI SDK `ToolSet` from a service — [guide](../guide/mcp-and-agents.md#ai-agents--mountagent) |
 | `defineRuntimeTool` | function | define one validated pathless operation for MCP, Agent or both — [guide](../guide/mcp-and-agents.md#pathless-runtime-tools-and-multimodal-results) |
+| `createRuntimeToolFactory` | function | bind shared identity and Zod-validated per-call context for runtime tools — [guide](../guide/mcp-and-agents.md#pathless-runtime-tools-and-multimodal-results) |
 | `createToolInvoker` | function | compile an exposure-aware in-process dispatcher over the canonical tool runner — [guide](../guide/mcp-and-agents.md#in-process-calls--createtoolinvoker) |
 | `createCli` | function | a command-line program from contracts — [guide](../guide/cli.md) (also on `stitchkit/cli`) |
 | `createToolkit` | function | context-typed tool mounts — [guide](../guide/cli.md#typed-context) |
@@ -5029,6 +5207,12 @@ Server-only. Turns contracts into MCP and AI-agent tools. Needs the
 | `RuntimeToolDefinitionBase` | _type_ | common name, identity, input, exposure and MCP metadata fields |
 | `RuntimeToolDefinitionWithOutput` | _type_ | runtime definition whose handler and presenters share a validated output type |
 | `RuntimeToolDefinitionWithoutOutput` | _type_ | runtime definition with a void handler and no presentation callbacks |
+| `RuntimeToolFactory` | _type_ | identity/context-bound runtime-tool definition factory |
+| `RuntimeToolFactoryConfig` | _type_ | factory service identity and context schema |
+| `RuntimeToolFactoryDefinitionWithOutput` | _type_ | factory-authored runtime tool with a validated output schema |
+| `RuntimeToolFactoryDefinitionWithoutOutput` | _type_ | factory-authored void runtime tool without presenters |
+| `RuntimeToolFactoryHandlerContext` | _type_ | parsed factory context plus parsed tool input |
+| `RuntimeToolFactoryIdentityFields` | _type_ | per-tool action, semantic method and optional identity metadata |
 | `RuntimeToolIdentity` | _type_ | `{ serviceName, action, scope?, method, meta? }` for runtime lifecycle/audit |
 | `RuntimeToolHandlerContext` | _type_ | runtime context with the definition's parsed input |
 | `RuntimeToolOutput` | _type_ | output inferred from a runtime tool's optional Zod schema |
@@ -5133,7 +5317,7 @@ Advanced building blocks — the shared machinery the mounts are built on.
 | `ToolSurfaceTransport` | _type_ | tool collector transport: `'MCP' \| 'AGENT' \| 'CLI'` |
 | `ToolManifestConfig` | _type_ | mixed surface plus required model-facing `transport` and presentation options |
 | `coerceJsonArgs` | function | coerce JSON-stringified array/object tool arguments |
-| `flattenToolJsonSchema` | function | project structurally identifiable discriminated unions in a JSON Schema document into conservative object joins; never executes validation |
+| `flattenToolJsonSchema` | function | project structurally identifiable discriminated unions into conservative object joins; divergent fields retain every provable base kind in a deterministic `type` array, and the projection never executes validation |
 | `ToolPresentationSchema` | _type_ | immutable model-facing JSON Schema document shared by tool transports |
 | `MountableTool` | _type_ | one operation with separate executable CLI argument schema and model-facing presentation schema |
 | `ToolManifestEntry` | _type_ | one `buildToolManifest` row |

package/llms.txt

@@ -16,6 +16,7 @@ Build with stitchkit: define a contract once, then `implement` it and serve it (
 - [Observability](https://github.com/max-listov/stitchkit/blob/master/docs/guide/observability.md): request and tool-call logging via hooks, W3C trace context, createAuditHook
 - [Testing & deployment](https://github.com/max-listov/stitchkit/blob/master/docs/guide/testing-and-deployment.md): in-process testing; deploying on Bun and on Node (serveNode)
 - [Multi-tenant](https://github.com/max-listov/stitchkit/blob/master/docs/guide/multi-tenant.md): a /tenants/:id/… scenario end-to-end — scopePrefixes, scoped client, extend
+- [Frontend integrations](https://github.com/max-listov/stitchkit/blob/master/docs/guide/frontend-integrations.md): React Router resource routes and a separate Vite development proxy
 - [Upgrading](https://github.com/max-listov/stitchkit/blob/master/docs/guide/upgrading.md): moving a project across stitchkit versions; how breaking changes are marked
 
 ## Reference

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "stitchkit",
-  "version": "0.42.0",
+  "version": "0.43.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",
@@ -160,7 +160,7 @@
     "@types/json-schema": "^7.0.15",
     "@types/react": "^19.2.18",
     "@typescript/typescript6": "^6.0.2",
-    "ai": "^7.0.56",
+    "ai": "^7.0.58",
     "react": "^19.2.8",
     "react-query-kit": "^3.3.4",
     "socket.io": "^4.8.3",