stitchkit 0.80.0 → 0.81.0

package/llms-full.txt

@@ -59,11 +59,15 @@ own, recorded as an ADR.
 | `stitchkit/remote` | browser **and** server | stable | peer-free `implementRemote` for thin HTTP proxy processes |
 | `stitchkit/files` | server (Bun or Node) | stable | peer-free managed local-file boundary |
 | `stitchkit/telegram` | server (Bun or Node) | evolving | peer-free Telegram platform primitives — Mini App `initData` verification and Bot API send-failure classification |
+| `stitchkit/tracking` | browser **and** server | evolving | visitor-tracking mechanics — `createTrackingClient`, the tab-shared outbox, the page-leave beacon, attribution, the contract factory; no event vocabulary, no React |
+| `stitchkit/tracking/server` | server (Bun or Node) | evolving | the decisions a tracking backend makes — dispositions, visit lease over an application-owned store, active intervals, presence; no database |
+| `stitchkit/release` | browser **and** server | evolving | a page follows the release it was built for — `createReleaseMarker` on the server, `createReleaseWatcher` in the browser, the `X-Build-Id` header and a socket event between them |
+| `stitchkit/geo` | server (Bun or Node) | evolving | managed GeoIP reader generations, last-known-good reload and the optional MaxMind adapter |
 | `stitchkit/observability` | server | stable | request/tool event projections — `createObservability`, trace context, sanitisation |
 | `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` | browser + 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 11 of the 25 minors since 0.56.2, most recently 0.75.0_ | optional durable conversation/run loop, history, models, prompts, fencing and events |
+| `stitchkit/react` | browser + server rendering | stable | `createCursorQuery`, `createCacheBridge`, QueryClient and `ApiError` retry policy |
+| `stitchkit/agent-runtime` | server | evolving<br>_redefined in 11 of the 26 minors since 0.56.2, most recently 0.75.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 |
@@ -71,7 +75,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` | browser + server | evolving<br>_redefined in 6 of the 25 minors since 0.56.2, most recently 0.79.0_ | managed resource graph, readiness, admission, schedules, subtree restart and bounded shutdown |
+| `stitchkit/application` | browser + server | evolving<br>_redefined in 6 of the 26 minors since 0.56.2, most recently 0.79.0_ | managed resource graph, readiness, admission, schedules, subtree restart 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` |
 | `stitchkit/application/schemas` | browser + server | evolving | the application's snapshot, health and shutdown schemas alone, without the kernel |
@@ -182,6 +186,7 @@ map — feature → packages:
 | MCP host/client tests | `@modelcontextprotocol/client` |
 | MCP Apps UI widgets | `@modelcontextprotocol/ext-apps` |
 | React data layer (`stitchkit/react`) | `@tanstack/react-query` `react-query-kit` |
+| MaxMind GeoIP (`stitchkit/geo`) | `maxmind` |
 | **Socket.IO server on Bun** | `socket.io` `@socket.io/bun-engine` |
 | **Socket.IO server on Node** | `socket.io` |
 | Socket.IO client | `socket.io-client` (runtime peer; unrelated root declarations remain peer-free) |
@@ -237,6 +242,341 @@ and recovery stay framework-owned primitives, while model choice, permissions,
 executables and OS isolation remain application policy.
 
 
+==============================================================================
+# Guide: Release  (docs/guide/release.md)
+==============================================================================
+
+# Release
+
+A tab that outlives a release keeps running a bundle the server no longer
+serves. `stitchkit/release` makes the page follow the release it was built
+for: the server names its current frontend build, the browser compares that
+to its own, and reloads under a policy you declare. Both halves are
+**evolving**. → ADR 0167
+
+## The server: a marker and two channels
+
+```ts
+import { readFileSync } from 'node:fs'
+import { createReleaseMarker } from 'stitchkit/release'
+import { bindReleaseRefreshSignal, createServer } from 'stitchkit/server'
+
+// Where the *active* release wrote its build id. After a frontend-only
+// release the backend may still run from an older root — read the pointer to
+// the current one, not the process's own cwd. `null` means "no release": a
+// dev server under HMR stays silent.
+const release = createReleaseMarker({
+  read: () => (env.RELEASE_ROOT ? readFileSync(`${env.RELEASE_ROOT}/current/frontend/.next/BUILD_ID`, 'utf8') : null),
+  onError: (error) => logger.warn('release marker', error), // an unreadable file, a value that is not an id, a subscriber that threw
+})
+
+const server = createServer({ services, cors, release })
+
+// A deploy that replaced the frontend without restarting the backend sends
+// SIGUSR2; the marker re-reads and tells its subscribers.
+bindReleaseRefreshSignal(release, { onRefresh: (r) => logger.info('build', r) })
+```
+
+With `release` configured, **every** response — success, error, raw route —
+carries `X-Build-Id`, and `DEFAULT_CORS_EXPOSE_HEADERS` lets a cross-origin
+page read it. That is the universal channel: any application that makes HTTP
+requests has it, with no socket and no polling of its own.
+
+Where a Socket.IO server exists, add the fast path:
+
+```ts
+import { bindReleaseToSocketServer } from 'stitchkit/release'
+
+bindReleaseToSocketServer(io, release) // event `release` on connection and on change
+```
+
+A connection re-reads the file before it is answered, so a deploy signal the
+process missed while it was down is repaired by the next client that connects.
+
+Two things to keep straight: a custom `cors.exposeHeaders` **replaces** the
+default list, so add `X-Build-Id` to yours or a cross-origin page cannot read
+it; and do not list `SIGUSR2` in `bindProcessSignals` as well, or a deploy
+would shut the server down.
+
+## The deploy step
+
+The framework binds the signal; **your release sends it**, after the new
+frontend is active:
+
+```bash
+pm2 sendSignal SIGUSR2 my-backend      # or: kill -USR2 <pid>
+```
+
+Name it in the release steps of the project. A backend restart needs no
+signal — the marker reads on start, and every reconnecting browser asks.
+
+## The browser: a watcher and its feeds
+
+```ts
+import { createHttpClient } from 'stitchkit'
+import { createReleaseWatcher, observeReleaseFromSocket } from 'stitchkit/release'
+
+const release = createReleaseWatcher({
+  own: env.NEXT_PUBLIC_BUILD_ID ?? 'dev', // what THIS bundle was built with; `dev` never reloads
+  policy: 'when-hidden',           // or 'immediate' | 'on-navigation'
+  maxDeferMs: 15 * 60 * 1000,
+  onStale: () => toast('A new version is ready'),
+})
+
+const http = createHttpClient({ baseUrl, release })   // reads X-Build-Id from every response
+observeReleaseFromSocket(socket, release)             // and the socket event, where there is one
+```
+
+`observe` compares to `own`, never to the first id it happened to hear — a
+tab that loaded a cached bundle after the release is exactly the tab that must
+reload. An `own` of `dev` (configurable via `ignore`), or no `own` at all,
+never reloads, so a development bundle against a production API is not sent
+in a loop. And one reload per id: the id a reload was attempted for is kept
+in session storage, and if the page comes back and the server still names it,
+the server is wrong about what it serves (a marker reading the wrong root, a
+cached response) — the page stays, `stale()` is true, `onStale` has fired,
+and nothing loops.
+
+| Policy | Reloads |
+|--------|---------|
+| `immediate` | now — a chat, a dashboard |
+| `when-hidden` | when the tab is next hidden, or at `maxDeferMs` — a page with forms |
+| `on-navigation` | when you call `release.navigated()` on a route change, or at `maxDeferMs` — an SPA where a full load replaces a transition |
+
+`browserReleaseHost()` is what the watcher reads from a tab; a test passes its
+own `host` and drives visibility, the timer and `reload` by hand. Without a
+`document` (server-side rendering) the default host is inert: `observe`
+records the verdict and reloads nothing.
+
+## Adopting it
+
+1. Bake the build id into the bundle: `NEXT_PUBLIC_BUILD_ID=$(git rev-parse
+   --short HEAD)` at build time, or Next's `generateBuildId`. Without it the
+   watcher has no `own` and never reloads.
+2. Point `read` at the id of the **active** release, not the process's cwd.
+3. Add `release: (data: { buildId: string | null }) => void` to your
+   `ServerToClientEvents` map where you type your socket, so your own `on`
+   knows the event the binding emits.
+4. Send `SIGUSR2` from the deploy step that activates a frontend without
+   restarting the backend, and name that step in the project's release steps.
+
+
+==============================================================================
+# Guide: Visitor tracking  (docs/guide/tracking.md)
+==============================================================================
+
+# Visitor tracking
+
+`stitchkit/tracking` is the browser half of visitor tracking — the outbox, the
+visit lease, the page-leave beacon, visible time, scroll milestones,
+declarative clicks, attribution — and `stitchkit/tracking/server` is the set of
+decisions a tracking backend makes about what arrives. Neither has an event
+vocabulary of its own, a database, or a React component: those are the
+application's, and the boundary is deliberate. → ADR 0166
+
+Both entrypoints are **evolving**.
+
+## What the framework owns, and what you do
+
+| Framework | Application |
+|-----------|-------------|
+| the event envelope, the batch, the dispositions, the visit entry and lease schemas | the event **types**, their metadata, their labels |
+| the tab-shared outbox with reserved sequences and a short flush lease | which storage adapter (IndexedDB in a tab) |
+| the page-leave beacon that arrives, and its queued insurance copy | the session, the router, the React provider |
+| visible time, scroll milestones, `data-track` clicks, UTM first/current touch | the referrer → source map, the attribute names |
+| `dispositionTrackingBatch`, `issueVisitLease`, `activeIntervalOf`, presence | the tables, the transaction, adoption, geo, reports |
+
+## Contract
+
+```ts
+import { createTrackingContract } from 'stitchkit/tracking'
+
+export const tracking = createTrackingContract({
+  scope: 'public',
+  eventTypes: ['PAGE_VIEW', 'PAGE_LEAVE', 'SCROLL_DEPTH', 'SESSION_HEARTBEAT', 'CLICK', 'OUTBOUND_CLICK', 'INTERACTION', 'ITEM_VIEW'],
+  // eventExtras: z.object({ locale: z.string() }),   // fields you carry beside the envelope
+})
+```
+
+Two operations: `bootstrap` (`POST /visit`) issues or renews a visit lease,
+`track` (`POST /events`) receives a batch. `track` declares
+`safelistedBody: true`, because the page-leave event is a string beacon — the
+only body a document that is being unloaded can deliver to another origin —
+and that in turn requires an explicit `cors.origin` allow-list on the server.
+Read [safelisted request bodies](./server.md#safelisted-request-bodies-beacons)
+before deploying: it is one rule, and it is the one that keeps the beacon path
+from being a CSRF hole.
+
+`scope: 'public'` is the usual choice: the landing page is read by anonymous
+visitors, and their path is part of the funnel. Identity comes from the cookie
+on the server side; the client claims nothing about itself.
+
+## Browser
+
+```ts
+import {
+  browserTrackingHost, CONVENTIONAL_TRACKING_EVENT_TYPES, createTrackingClient,
+  createTrackingOutbox, indexedDbOutboxStorage,
+} from 'stitchkit/tracking'
+
+// Only the types the browser writes — a server-side event must not be trackable here.
+type BrowserEvents = Pick<EventMetadataMap, ClientTrackingEventType>
+
+const client = createTrackingClient<BrowserEvents>({
+  host: browserTrackingHost(),
+  buildId: env.NEXT_PUBLIC_BUILD_ID, // a typed env accessor; the client refuses `undefined`
+  builtin: CONVENTIONAL_TRACKING_EVENT_TYPES,       // your names for the events the client emits
+  bootstrap: (entry) => api.tracking.bootstrap(entry),
+  deliver: (batch) => api.tracking.track(batch),   // or a socket first, HTTP as the fallback
+  unloadUrl: urls.tracking.track(),
+  outbox: createTrackingOutbox(indexedDbOutboxStorage('my-app-tracking')),
+  referrerMap: [{ pattern: /t\.me|telegram\.org/, source: 'telegram', medium: 'social' }],
+  isAction: isInteractionAction,
+  onVisit: (visitId) => rum.setVisit(visitId),
+})
+```
+
+`EventMetadataMap` is your `{ [type]: metadata }` map; `track` is typed by it:
+
+```ts
+client.track('ITEM_VIEW', { itemId, itemTitle })
+client.track('SIGN_OUT')
+```
+
+Two knobs match the client to your schema: `batchSize` is the contract's
+`maxEventsPerBatch` (a larger batch is a `400` the outbox can never retire),
+and `decorate` adds your `eventExtras` — a locale, an area, or the identity a
+client that cannot send headers on unload has to carry in the body — to every
+event as it is minted, so the outbox, the beacon and `deliver` all see it:
+
+```ts
+createTrackingClient<BrowserEvents, TrackingEventEnvelope<keyof BrowserEvents> & { locale: string }>({
+  decorate: (event) => ({ ...event, locale: currentLocale() }),
+  // …
+})
+```
+
+A `bootstrap` operation that needs extra fields of its own (a locale, a RUM
+flag) is not the factory's: build the `entry` schema with
+`createTrackingSchemas(…).entry.extend({ … })` and declare that endpoint yourself.
+
+The client owns the mechanics that were the same in every application that
+wrote them: the visit lease and its renewal after a long sleep, a pending queue
+until the visit exists, synchronous event identity from a block of reserved
+sequence numbers, the outbox and its flush lease, one bounded delivery retry,
+the page-leave beacon *and* its queued copy, additive visible time, scroll
+milestones, `data-track` / `data-track-action` clicks, heartbeats. It does not
+own the router or React — tell it about navigation, and wrap it yourself:
+
+```tsx
+const TrackerContext = createContext<TrackFn<BrowserEvents> | null>(null)
+
+export function TrackingProvider({ children }: { children: React.ReactNode }) {
+  const [client] = useState(() => createTrackingClient<BrowserEvents>({ /* as above */ }))
+  const pathname = usePathname()
+  const search = useSearchParams().toString()
+  useEffect(() => client.start(), [client])
+  useEffect(() => client.onNavigate(pathname, search ? `?${search}` : ''), [client, pathname, search])
+  return <TrackerContext.Provider value={client.track}>{children}</TrackerContext.Provider>
+}
+
+export const useTracker = () => useContext(TrackerContext) ?? (() => { throw new Error('outside TrackingProvider') })()
+```
+
+A component that records "opened X" can mount twice on one page; keep that
+memory at document scope with `createOncePerPage`, not in a ref.
+
+### Why these details are not optional
+
+Four of them were found the expensive way, by consuming applications, and each
+is a test in this repository that reddens when the mechanism is put back:
+
+- the beacon body is a **string** — a `Blob` typed `application/json` reports
+  `true` and dies on the preflight it cannot have;
+- the event gets its sequence number **before** it is written — awaiting the
+  outbox inside `pagehide` loses the event with the document;
+- the flush lease is **short and released on leave** — a ten-second lease a
+  dying document kept delayed the next document's first flush by ten seconds;
+- `oncePerPage` lives at document scope — a remounted component has fresh refs.
+
+## Server
+
+The server half is pure. Read from your database, decide, write:
+
+```ts
+import { activeIntervalOf, dispositionTrackingBatch, hashTrackingEvent, issueVisitLease } from 'stitchkit/tracking/server'
+
+track: async ({ input, ipAddress, userAgent }) => {
+  const actorOwnerId = session?.userId ?? null
+  const visits = await db.visit.findMany({ where: { id: { in: input.events.map((e) => e.visitId) } } })
+  const stored = await db.trackingEvent.findMany({ where: { clientEventId: { in: input.events.map((e) => e.eventId) } } })
+  const decided = dispositionTrackingBatch({
+    events: input.events,
+    visits: visits.map((v) => ({ id: v.id, browserStreamId: v.browserStreamId, ownerId: v.userId })),
+    existing: new Map(stored.map((e) => [e.clientEventId, e.clientPayloadHash])),
+    actorOwnerId,
+    userAgent,
+  })
+  const now = new Date()
+  await db.$transaction(async (tx) => {
+    for (const visitId of decided.adoptable) await adoptVisit(tx, visitId, actorOwnerId, now)
+    await tx.trackingEvent.createMany({
+      data: decided.accepted.map((event, ordinal) => ({
+        ...yourColumns(event), clientPayloadHash: hashTrackingEvent(event), serverItemOrdinal: ordinal, createdAt: now,
+      })),
+    })
+    for (const event of decided.accepted) {
+      const interval = activeIntervalOf(event, now)
+      if (interval) await tx.activeTimeInterval.upsert(/* by interval.intervalId */)
+    }
+  })
+  return { accepted: decided.accepted.length, dispositions: decided.dispositions }
+}
+```
+
+`hashTrackingEvent` is `sha256(JSON.stringify(parsedEvent))` with no key
+sorting — exactly what applications already store, so a migration does not
+spend a week reporting conflicts. `decided.conflicts` names duplicates whose
+payload changed; log them.
+
+`issueVisitLease` runs the visit algorithm over a store you implement — six
+methods over your tables, inside a lineage lock you hold (`pg_advisory_xact_lock`
+over the browser stream id is the usual one):
+
+```ts
+const store: TrackingVisitStore<Prisma.TransactionClient> = {
+  withLineageLock: (lineage, fn) => db.$transaction(async (tx) => {
+    await tx.$executeRaw`SELECT pg_advisory_xact_lock(hashtext(${lineage}))`
+    return fn(tx)
+  }),
+  findActive: (tx, q) => tx.visit.findFirst({ where: { /* q.browserStreamId, q.cutoff, ownership */ } }),
+  touch: (tx, id, now, health) => tx.visit.update({ where: { id }, data: { lastActivityAt: now, ...health } }),
+  adopt: (tx, visit, ownerId, now) => /* assign the owner, back-fill events, record the merge */,
+  endOpen: (tx, lineage, now) => tx.visit.updateMany({ where: { browserStreamId: lineage, endedAt: null }, data: { endedAt: now } }),
+  create: (tx, visit, health) => tx.visit.create({ data: { id: visit.id, ...deviceGeoAndSource(visit) , ...health } }),
+}
+
+bootstrap: ({ input, userAgent }) =>
+  issueVisitLease(store, { ownerId: session?.userId ?? null, userAgent }, input, { ownership: 'adopting' })
+```
+
+`ownership` is the one policy two applications disagreed on: `'adopting'`
+continues an anonymous visit and gives it to the caller who signs in — the
+path from the landing page to the first signed-in action becomes one path; `'owned'` never
+continues an anonymous visit, for an application where every visitor already
+has an identity. A bot gets a lease that no store holds, so its events are
+`identity-invalid` and nothing of it reaches a report.
+
+`createPresenceRegistry` is who is here now, in this process: touch it from
+`track`, read it for a live feed. It is honestly empty after a restart.
+
+## Not here
+
+GeoIP, event labels, funnels, reports, the analytics page, Socket.IO push into
+an admin UI, RUM — application code, and the reason two applications' tracking
+looks different even though their mechanics are now one.
+
+
 ==============================================================================
 # Guide: Contracts  (docs/guide/contracts.md)
 ==============================================================================
@@ -331,11 +671,13 @@ with output and a default bodyless `204` without it.
 
 The three schemas are distinct on purpose:
 
-- **`params`** — values in the URL path. `path: '/:id'` ⇒
-  `params: z.object({ id: z.string() })`. The client takes them from the call
-  argument and substitutes them into the URL. A terminal wildcard is explicitly
-  named: `path: '/:slug/*filePath'` with
-  `params: z.object({ slug: z.string(), filePath: z.string() })` matches both
+- **`params`** — values in the URL path. `path: '/:id'` infers
+  `{ id: string }` and materializes the same Zod string schema for HTTP, OpenAPI,
+  MCP, Agent and CLI. Declare `params: z.object({ id: z.uuid() })` only when the
+  path value needs validation or coercion; an explicit schema must cover every
+  name in the path. The client takes params from the call argument and
+  substitutes them into the URL. A terminal wildcard is explicitly named:
+  `path: '/:slug/*filePath'` matches both
   `/foo/page` and `/foo/a/b`; the handler reads `ctx.params.filePath` as
   `'page'` or `'a/b'`. Bare `/*`, invalid/duplicate names and a wildcard before
   the final segment fail at contract definition.
@@ -350,7 +692,7 @@ caller passes a single flat object, the client routes each field to the path or
 the body.
 
 ```ts
-// path: '/:id', params: { id }, input: { text }
+// path: '/:id' infers params: { id: string }; input: { text }
 await api.update({ id: '1', text: 'new' })   // PUT /users/1  body: { text: 'new' }
 
 // path: '/:slug/*filePath', params: { slug, filePath }
@@ -418,6 +760,11 @@ 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.
 
+Consequently, `expose: ['HTTP']` is redundant inside a factory configured with
+`toolExposure: 'explicit'`: omit it unless the explicit spelling is useful to a
+local reader. Add `MCP`, `AGENT` or `CLI` only on endpoints that intentionally
+join those surfaces.
+
 Tool transports (`MCP`, `AGENT`) skip four kinds of endpoint automatically:
 `multipart` (a file upload is not a tool call),
 [`rawResponse`](./server.md#raw-response-endpoints) (its answer is bytes, which
@@ -1285,12 +1632,83 @@ not retain the text. `maxJsonBodyBytes` may also be set once on `createServer` /
 `createHandler`; a route value wins. Both limits are opt-in and abort an
 oversized stream before it is fully buffered. → ADR 0051
 
+## Safelisted request bodies (beacons)
+
+A body the router reads is `application/json`, and a non-empty body with any
+other `Content-Type` is a `400`. That is deliberate: a `text/plain` body is a
+CORS *simple* request, sent with cookies from any site before the browser asks
+whether the page may read the reply — so requiring JSON forces a preflight, and
+the preflight is where a foreign form is stopped.
+
+A page that is being unloaded does not get a preflight. `navigator.sendBeacon`
+with an `application/json` blob and `fetch({ keepalive: true })` with a JSON
+`Content-Type` both report success and both die before the server sees them
+when the API is on another origin. A beacon with a **string** body is
+`text/plain` and arrives. Declare the endpoint that receives it:
+
+```ts
+const tracking = defineContract(
+  { prefix: 'tracking', scope: 'public' },
+  {
+    track: {
+      method: 'POST', path: '/events', desc: 'Batch track browser events',
+      safelistedBody: true,
+      maxJsonBodyBytes: 256 * 1024,
+      input: TrackEventsRequestSchema,
+      output: TrackEventsResponseSchema,
+    },
+  },
+)
+
+// browser, on `pagehide`
+navigator.sendBeacon(urls.tracking.track(), JSON.stringify(batch)) // text/plain;charset=UTF-8
+```
+
+The body is parsed by the same JSON parser, validated against the same `input`
+and bounded by the same `maxJsonBodyBytes`; `application/json` keeps working.
+What changes is one rule, and it is the rule that keeps the door from being a
+hole: a `text/plain` body is accepted **only from an `Origin` on the server's
+explicit `cors.origin` allow-list**. Everything else is a `403` before the text
+is read:
+
+| Request | Outcome |
+|---------|---------|
+| `Origin` on the allow-list (string or list, case-insensitive) | parsed |
+| `Content-Type: text/plain; charset=application/json` from a foreign origin | `403` — the media type is compared whole, never as a substring |
+| `Origin` of a site the server never named | `403` |
+| `Origin: null` — sandboxed iframe, cross-origin redirect, `file://` | `403` |
+| no `Origin` header | `403` |
+| server `cors.origin: '*'` | `403` — a wildcard is not an allow-list |
+| server without `cors` | `403` — there is no allow-list |
+| `application/json` from any origin | unchanged — never subject to the check |
+
+The check is a browser invariant, not authentication: a `curl` with a stolen
+cookie and a forged `Origin` passes, and that is an authenticated call, not a
+cross-site one. Two things follow for the application:
+
+- **`sendBeacon` sends no headers.** A bearer-authenticated client has to put
+  its token in the body — and the body is read *after* `authorize`, so that
+  token is available in `beforeHandle` or the handler, never in an auth hook.
+  Cookie-authenticated apps are unaffected.
+- **`POST` only.** `defineContract` refuses the flag on `GET`, `HEAD`, `PUT`,
+  `PATCH`, `DELETE`, multipart, streaming and input-less endpoints: none of them
+  is a simple request with a JSON body, so the flag would only widen the surface.
+
+Unlike `rawBody`, the flag does not force `expose: ['HTTP']` — a beacon endpoint
+may still be a tool; only HTTP body parsing changes. OpenAPI lists both media
+types with one schema. → ADR 0165
+
+A [raw route](#raw-routes) has none of this: `parseBody` reads any
+`Content-Type`, so a raw beacon route is reachable from any site with the
+user's cookies unless the route checks `Origin` itself. Prefer the flag.
+
 ### Choosing an HTTP boundary
 
 | Need | Contract declaration | What remains framework-owned |
 |------|----------------------|------------------------------|
 | Typed JSON request/response | ordinary `input` / `output` | routing, auth, schemas, hooks, client, OpenAPI |
 | HMAC-signed JSON | `rawBody: true` + `input` / `output` | the same pipeline plus the exact decoded request text |
+| Page-unload beacon from another origin | `safelistedBody: true` + `input` / `output` | the same pipeline; a `text/plain` body is admitted only from an allow-listed `Origin` |
 | File upload | typed `multipart` descriptor | file cardinality/limits, text input validation and client form encoding |
 | File, stream or redirect response behind contract auth | `rawResponse: true` | request parsing, route identity, auth and typed URL/client surface |
 | Transport that cannot be expressed as the contract pipeline | `RawRoute` | only raw routing, CORS, request hook and error normalisation |
@@ -1455,12 +1873,20 @@ createServer({
     {
       method: 'POST',
       path: '/webhooks/:provider',
+      serviceName: 'webhooks',
+      action: 'receive',
       handler: (req, ctx) => handleWebhook(ctx.params.provider, req),
     },
   ],
 })
 ```
 
+`serviceName` and `action` are optional observability identity. Declare
+`serviceName` when audit, logging, sampling or another cross-cutting policy
+groups this raw route with a service; add `action` when the policy needs an
+operation within that service. Stitchkit never derives either from `path`.
+`action` without `serviceName`, and empty identity strings, fail at startup.
+
 A path may be exact, carry `:param` segments, or end in `/*filePath` for a prefix
 wildcard — and the two combine: `/app/:slug/*filePath` matches `/app/x/a/b` with
 `ctx.params.slug === 'x'` and the remainder in `ctx.params.filePath` (a SPA
@@ -5153,7 +5579,7 @@ description: Compose process-local resources, schedules, readiness, drain and op
 type: architecture
 status: active
 created: 2026-08-23
-updated: 2026-08-23
+updated: 2026-09-04 14:11 +07:00
 ---
 
 # Managed application kernel
@@ -5663,6 +6089,40 @@ underlying Promise actually settles. `drain()` therefore reports real work;
 `force()` closes admission and reports remaining work without claiming to have
 terminated it. → ADR 0118.
 
+### Bounded revision wake-up
+
+Use `createRevisionSignal` when several operations need to wait for the same
+process-local fact to change, but the change itself is not a queue item:
+
+```ts
+const connectionsChanged = createRevisionSignal({ maxWaiters: 256 })
+
+const observed = connectionsChanged.getSnapshot().revision
+const result = await connectionsChanged.wait(observed, {
+  signal: request.signal,
+  timeoutMs: 10_000,
+})
+
+// After changing the canonical connection state:
+connectionsChanged.advance()
+```
+
+`wait(after)` resolves immediately when the signal is already newer than
+`after`; this closes the race between reading a snapshot and registering the
+wait. Waiting on the current revision parks one operation, up to `maxWaiters`.
+Every terminal result carries the revision it observed and distinguishes
+`changed`, `timed-out`, `aborted`, `closed` and `capacity`. A future `after` is
+a caller error rather than a revision the signal could honestly promise to
+reach.
+
+One advance wakes every older waiter. It is not consumed by the first reader,
+does not retain event payloads and has no replay history. A bounded channel is
+for delivering items to one reader; a credit window grants a finite resource.
+
+The signal is already its whole lifecycle handle. Call its idempotent `close()`
+from the `close` phase of the managed resource that owns the changing fact;
+there is no second managed-resource wrapper around the same state. → ADR 0163.
+
 ### Bounded delivery and byte credit
 
 `createBoundedChannel` is for one asynchronous reader when an event bus is not a
@@ -5898,6 +6358,79 @@ Durable job tables, lifecycle journals/outboxes, provider inboxes and business
 retry rules do **not** disappear. They were never process-local glue and remain
 application-owned.
 
+## Durable process facts and owner notifications
+
+`createProcessLifecycleLedger` records a bounded versioned list of process runs.
+Start, readiness and shutdown target both `runId` and `pid`, so hot reload and
+PID reuse cannot close the wrong generation. A start classifies what happened to
+the newest run before it, and the classification is decided by three facts —
+whether that run recorded its own exit, whether the pid is the same, and whether
+the version changed:
+
+| newest run | same pid | version | `previousExit` | predecessor's `termination` |
+|---|---|---|---|---|
+| none | — | — | `first-boot` | — |
+| recorded `stoppedAt` | — | — | `clean` / `forced` / `abnormal` as recorded | unchanged |
+| still `active` | yes | — | `hot-reload` | `hot-reload`, closed at the new start |
+| still `active` | no | changed | `handoff` | stays `active`; it records its own stop later |
+| still `active` | no | same | `abnormal` (default) | `abnormal`, closed at the new start — an upper bound, the crash time is unknown |
+
+A version of `unknown` on either side is never a version change, so a dev build
+after a crashed release reads `abnormal`, not `handoff`. `forced` means the
+process itself acknowledged a kill; `abnormal` means a successor found it dead.
+
+The last row is a choice, and the default is the single-process deployment:
+one process per build, a new pid of the same build means the old one stopped
+answering. Where two processes of **one** build overlap on purpose — a
+cluster, a zero-downtime reload of the same build — pass
+`sameVersionOverlap: 'handoff'` to the ledger, and the predecessor stays
+`active` until it records its own shutdown. The cost of that setting is
+symmetric: a real crash under it is reported as a handoff and the dead run
+stays `active` in the ledger until retention drops it. The list is kept in the
+order the transitions wrote it — every write goes through one atomic update,
+so that order is the causal one, and a successor whose clock lags its
+predecessor still finds it at the head; `startedAt` is data, not the sort key.
+Retention (`retain`, default 20) drops finished runs first and an active one —
+a live handoff predecessor — only when nothing finished is left. Facts are
+published through the ledger's own subscription and resource value;
+`ApplicationEventSink` remains the strict application-state stream.
+
+`createNotificationOutbox` is the transport-neutral durable delivery side. It
+persists before send, claims an item with an expiring lease, carries one stable
+idempotency key into the transport, retries under an injected clock and records
+terminal drops. The guarantee is at-least-once: a crash after remote acceptance
+but before the receipt is persisted may redeliver, so transports should use the
+key when they support deduplication. The retry budget is sized for the outage
+an owner notification has to outlive, not for a flaky call: the default backoff
+doubles from one second and caps at sixty (`backoffDelay`, the one formula the
+client's resumable streams also use, with jitter 0), and the 99 waits between
+the default `maxAttempts` of 100 sum to 1+2+4+8+16+32 s plus 93 × 60 s — about
+94 minutes — before `onDropped` sees `attempt-limit`.
+`state()` is a read and never fails on the bounds a transition enforces — a file
+that grew past `maxStateBytes` under an older limit is inspectable and is
+trimmed by the next transition. Two bounds do fail loudly: `enqueue` past
+`maxQueue` throws rather than dropping silently, and a `backoffMs` that returns
+`NaN`, a negative or an infinite delay rejects the flush. `stop()` lets the
+send in flight finish and claims nothing more; a `send` without its own
+deadline holds `stop()` — and so the resource's `force()` — for that one call,
+so give the transport a timeout. Superseding a key that is being sent right now
+does not recall it: the send completes, and only its receipt is not written.
+
+Both primitives depend on the structural `StateStore`. On a server,
+`createFileStateStore` supplies the shared Zod-validated JSON adapter with an
+inter-process lock, unique temporary file, fsync and atomic rename. The lock
+is a file with a heartbeat: the holder refreshes its mtime every third of
+`staleLockMs` (default 3 s), a contender waits up to `lockTimeoutMs` (default
+10 s), and the stale bound must sit inside the timeout — otherwise a crashed
+holder blocks every update until the lock ages out, which the constructor
+refuses. A lock whose heartbeat is stale is reclaimed once its recorded pid is
+gone; a live or unverifiable pid (a reused number, another user's process)
+keeps it for ten stale bounds — and never fewer than thirty missed heartbeats,
+so a scheduler stall on a loaded host cannot pull a live lock from under its
+holder — after which the heartbeat wins and the lock is abandoned. Temporary files a crashed writer left beside the state are swept on
+the store's first update. Ledger corruption may be declared reconstructable;
+an outbox must fail closed rather than silently discard pending delivery.
+
 
 ==============================================================================
 # Guide: Generic application primitives  (docs/guide/primitives.md)
@@ -7607,6 +8140,40 @@ gives you the contract and the metadata (`idempotent`, the open `source` tag,
 `createRetainedTopics`); the wire and the per-call execution stay yours. See
 [ADR 0028](../decisions/0028-revert-contract-dispatcher.md).
 
+## Authenticated room registry and replay
+
+`bindSocketRegistry` composes over `bindRealtimeServer`; it never authenticates
+a socket a second time and never creates another outbound validator. The
+identity in `connection.raw.data` has already passed the Socket.IO handshake.
+
+`rooms(identity)` names the rooms a connecting identity may be in; the registry
+joins them and refuses a later `join` to any other. The disconnect listener is
+attached before that lookup is awaited, so a socket that drops while its
+permissions are still being resolved never becomes a member. `registry.room(name)` mints
+the opaque `AuthorizedSocketRoom` for a name — the token proves the name came
+through this registry, not that anyone is in the room, so a room with no open
+tab is an ordinary `emitTo` target that reports zero recipients. The registry
+owns join/leave, multiple sockets per identity, immutable snapshots and
+listener cleanup.
+
+Replay is revisioned: while a socket's snapshot is open, frames sent through
+`emitTo` to its rooms are held back and delivered after the snapshot, so the
+socket never sees a delta for state its snapshot already contains, nor a
+snapshot that predates a delta it already received. A snapshot taken across a
+`revision` change is retried up to `replayAttempts` (default 3). The hold-back buffer is
+bounded by `maxBufferedFrames` (default 1000): past it the attempt is abandoned
+and retried, and when the attempts are spent `onResyncRequired(socketId,
+identity)` fires with nothing half-delivered — the application decides what a
+resync means for that socket. A retry relies on the fresh snapshot carrying
+what the abandoned frames carried, which holds when every emitted change also
+moves `revision`; without a `revision` the registry has no way to tell, so
+declare one wherever replay matters. Room tokens are recognised, not
+remembered: a token the application keeps stays valid for the life of the
+registry, and a name seen once does not live on in a map. This ordering exists only for frames that go
+through `emitTo`; a broadcast through `realtime.to(room).emit` reaches the
+socket immediately, replay or not, so keep room traffic whose order matters
+relative to the snapshot on the registry.
+
 
 ==============================================================================
 # Guide: Live data  (docs/guide/live.md)
@@ -8390,8 +8957,29 @@ session.clear()         // → a Set-Cookie value that expires it
 ```
 
 `defineCookie` bundles a cookie's name and options into a typed handle, so the
-config is not repeated at every call site. `parseCookies(header)` and
-`serializeCookie(name, value, opts)` are the lower-level primitives.
+config is not repeated at every call site. `parseCookies(header)`,
+`parseCookieHeader(header)` and `serializeCookie(name, value, opts)` are the
+lower-level primitives.
+
+**Two cookies, one name.** A browser sends every cookie whose domain and path
+match, so a `sid` on `.example.com` and a `sid` on `app.example.com` both arrive
+— in an order the browser chooses (RFC 6265 §5.4) and a server should not rely
+on (§4.2.2). `get` returns the **last** one by default, which is a fact of the
+header order, not a rule: the same session then validates in one browser and
+not in another. Name the behaviour you rely on, or refuse to guess:
+
+```ts
+const session = defineCookie({ name: 'sid', domain: '.example.com', duplicates: 'reject' })
+
+session.get(req)     // undefined when two *different* values arrive; the one value when they agree
+session.getAll(req)  // every candidate, in header order — validate each, clear the loser
+```
+
+`duplicates: 'reject'` turns the lottery into "no session", which a login page
+handles; `'first'` and `'last'` exist so an application can state which coin it
+flips. For a session cookie on a parent domain the durable fix is `getAll`:
+validate each candidate and answer with `clear()` for the one that lost, so the
+next request carries one.
 
 To set a cookie from a schema-validated JSON endpoint without losing its typed
 client result, declare [`responseMeta`](./server.md#typed-json-response-metadata)
@@ -8546,6 +9134,38 @@ onError: (ctx, err) => {
 }
 ```
 
+## One application vocabulary and one wire map
+
+`defineErrors` can also resolve Stitchkit's framework codes into the same
+application vocabulary. A status fallback is explicit because several
+application codes may legally share one HTTP status:
+
+```ts
+const vocabulary = defineErrors(
+  {
+    VALIDATION_ERROR: { status: 400, message: 'Invalid request' },
+    INTERNAL_ERROR: { status: 500, message: 'Internal error' },
+  },
+  {
+    fallback: { 400: 'VALIDATION_ERROR', 500: 'INTERNAL_ERROR' },
+    map: { FILE_TOO_LARGE: 'VALIDATION_ERROR' },
+  },
+)
+
+const onError = createErrorHook({ vocabulary })
+// `vocabulary` *is* the wire map: `codeMap` and `unmappedCode` cannot sit
+// beside it — the type forbids the combination and the runtime refuses it.
+// A `map` target must be declared under the framework code's own status
+// (`NOT_FOUND` → a 404 code, never a 410 one): the wire keeps the framework
+// status and carries your code, so `defineErrors` refuses the mismatch where
+// it already refuses a `fallback` under the wrong status.
+```
+
+An explicit per-code `map` wins over a status fallback. With
+`exhaustive: true`, `map` must be a complete `Record<StitchErrorCode, AppCode>`
+at compile time. Transport boundaries identify errors with `AppError.is`, not
+`instanceof`, so two bundled copies still agree.
+
 ## Domain errors — `defineErrors`
 
 Declare each domain code, HTTP status, default message and optional
@@ -8956,12 +9576,11 @@ route-match, *before* validation, so both are present on every event for a
 request that matched a contract route, including a pre-handler 400. Nothing to
 wire.
 
-They are **absent** on events that never reached a contract route: a raw route
-(`openApiRoute`, an MCP mount, any `rawRoutes` entry), a request short-circuited
-by `onRequest`, and an unmatched 404 or 405. Both fields are optional in
-`RequestEvent` for exactly that reason — a sink with a `NOT NULL` column on
-either, or a dashboard grouping by `(serviceName, action)`, has to allow for
-it.
+Raw routes may opt into the same context with `serviceName` and optional
+`action` on their `RawRoute` declaration. Without that declaration they remain
+absent, as they do for a request short-circuited by `onRequest` and an unmatched
+404 or 405. Both fields therefore remain optional in `RequestEvent`; a sink
+with a `NOT NULL` column on either still has to account for unattributed paths.
 
 When failure attribution itself is asynchronous, use `createErrorHook`'s
 `onError(error, info, ctx, endpoint)` observer. The framework awaits it before
@@ -9314,6 +9933,26 @@ hooks: {
 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.
 
+## Typed dimensions and bounded loggers
+
+`createDimensionsProjector` keeps endpoint metadata opaque. Configure typed
+request, result and error projections, then call its phase methods from the
+corresponding lifecycle hooks. Every projection writes through
+`setRequestDimensions`; repeated keys follow the declared `overwrite`,
+`preserve` or `error` policy. Two of its inputs are programming errors and
+throw, which fails the request rather than recording a lie: a repeated key
+under `collision: 'error'`, and a key named `__proto__` (it would set the
+bag's prototype — it can only arrive from parsed input, never from an object
+literal, which has no such own key).
+
+`createBoundedLogger` decorates the existing `StitchLogger` interface, so Pino,
+console and application sinks keep their ownership. It reuses the same
+sanitizer as request audit: sensitive keys, configured paths, URL fragments and
+`Error` fields are redacted before string/collection/depth/total-byte bounds are
+applied. Active trace, span, user and dimensions are reserved framework fields;
+caller data cannot overwrite them. A throwing getter, cyclic value or failing
+sink never escapes into application code.
+
 
 ==============================================================================
 # Guide: Testing & deployment  (docs/guide/testing-and-deployment.md)
@@ -10091,6 +10730,159 @@ Do not duplicate DTOs or handwritten API wrappers in either integration. The
 shared contract remains the only transport schema source.
 
 
+==============================================================================
+# Guide: React Query policy  (docs/guide/react.md)
+==============================================================================
+
+---
+title: React Query policy
+description: One request-local server client, one browser singleton and explicit retry rules for Stitchkit API errors
+type: guide
+status: active
+created: 2026-09-06
+updated: 2026-09-06
+---
+
+# React Query policy
+
+`stitchkit/react` contains policy adapters for TanStack Query. It does not own
+application queries, cache keys or authentication.
+
+## Query client per runtime
+
+Create the getter once. On the server, pass React's `cache` so identity is local
+to one render request. In the browser, the returned getter keeps one singleton
+inside this factory only:
+
+```ts
+import { cache } from 'react'
+import { createQueryClientFactory } from 'stitchkit/react'
+
+export const getQueryClient = createQueryClientFactory({
+  serverCache: cache,
+  queryClient: {
+    defaultOptions: { queries: { staleTime: 30_000 } },
+  },
+})
+```
+
+Pending queries are dehydrated so streaming SSR can resume them. Mutations do
+not retry by default. Every TanStack default may still be supplied through
+`queryClient`; a supplied query or mutation retry policy wins over the helper's
+defaults.
+
+## API error retries
+
+`apiErrorRetry()` returns a TanStack retry predicate. The default retries one
+network or `5xx` failure and refuses authorization, validation, abort and other
+`4xx` errors:
+
+```ts
+const retry = apiErrorRetry({
+  attempts: 2,
+  never: ['UNAUTHORIZED', 'FORBIDDEN'],
+  statusRanges: [[500, 599]],
+})
+```
+
+Ranges are inclusive. The predicate uses `ApiError.is`, so it remains valid when
+two bundles contain different copies of the class.
+
+Authentication remains application-owned. Memoize the application's own
+session query with `cache`; the generic starter does not invent a `getSession`
+endpoint or cookie vocabulary.
+
+
+==============================================================================
+# Guide: GeoIP  (docs/guide/geo.md)
+==============================================================================
+
+---
+title: GeoIP
+description: A server-only managed GeoIP reader with three observable states and last-known-good generation reloads.
+type: guide
+status: active
+created: 2026-09-06
+updated: 2026-09-06
+---
+
+# GeoIP
+
+`stitchkit/geo` is a server-only, evolving entrypoint for reading local GeoIP
+databases without making a database vendor part of the framework contract. It
+exposes a managed resolver, a peer-neutral reader boundary and an optional
+MaxMind adapter.
+
+## MaxMind
+
+Install `maxmind` only in applications that use the adapter:
+
+```bash
+bun add maxmind
+```
+
+Create one resolver and place it in the application resource graph:
+
+```ts
+import { createApplication } from 'stitchkit/application';
+import { createGeoIpResolver, createMaxMindGeoIpLoader } from 'stitchkit/geo';
+
+const geo = createGeoIpResolver({
+  paths: {
+    city: '/srv/geo/GeoLite2-City.mmdb',
+    asn: '/srv/geo/GeoLite2-ASN.mmdb',
+  },
+  loader: createMaxMindGeoIpLoader(),
+  reload: { intervalMs: 60_000 },
+  onError(error) {
+    logger.warn('GeoIP reader unavailable', { error });
+  },
+});
+
+const application = createApplication({ resources: [geo] });
+```
+
+The loader imports the optional peer lazily. City and optional ASN files open
+as one revision: if either changes during the open, the incomplete generation
+is discarded.
+
+## Three states
+
+`geo.snapshot()` distinguishes facts that must not be collapsed:
+
+- `uninitialized` — the managed resource has not started, or has closed;
+- `unavailable` — no usable database generation could be opened;
+- `ready` — lookups use a complete generation.
+
+A refresh failure while a reader is already `ready` preserves that reader and
+sets `reloadError`. This is last-known-good service, not a successful refresh.
+Applications decide whether that fact degrades their own readiness.
+
+## Lookups
+
+```ts
+const attribution = await geo.resolve(requestIp);
+```
+
+`resolve` returns `null` for invalid, loopback, private, link-local and otherwise
+non-public addresses without querying the reader. A database miss or lookup
+failure also returns `null`; `onError` receives operational failures. A result
+may include country, region, city, postal, coordinates, timezone and ASN fields.
+
+When a reload succeeds, new lookups move to the new generation immediately.
+The previous reader closes only after its in-flight lookups finish.
+
+## A custom reader
+
+Use `GeoIpReaderLoader` when the database is not MaxMind-compatible. `revision`
+must identify the complete input generation and return `null` when it cannot be
+read. `open` returns a reader for exactly that revision. Stitchkit serializes
+reloads, swaps generations and owns their close lifecycle.
+
+Download schedules, licenses, database paths, attribution persistence and
+analytics policy belong to the application.
+
+
 ==============================================================================
 # Guide: Upgrading  (docs/guide/upgrading.md)
 ==============================================================================
@@ -10108,7 +10900,10 @@ 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).)
+[`AGENTS.md` → Breaking changes](../../AGENTS.md).) `bun scripts/upgrade-plan.ts
+<installed> <target>` prints every breaking section your range crosses, oldest
+first, each with its **Who must act** line — the list this guide's migrations
+expand on.
 
 So upgrading is: read the `### ⚠️ Breaking changes` of every version *above* your
 current one *up to* your target, and apply each snippet.
@@ -10137,6 +10932,32 @@ 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.81.0
+
+**Path literals own string params.**
+
+An endpoint whose path contains `:id` or a terminal `*rest` no longer needs a
+duplicate `params: z.object({ …string() })` declaration. Remove schemas that do
+nothing beyond repeating path names:
+
+```ts
+// before
+{ path: '/projects/:projectId/*filePath',
+  params: z.object({ projectId: z.string(), filePath: z.string() }) }
+
+// after
+{ path: '/projects/:projectId/*filePath' }
+```
+
+Keep an explicit schema when it validates or coerces. It must cover every name
+in the path — an explicit schema that misses one now fails at `defineContract`
+with the path and the missing field named. Client calls and handler contexts
+infer the string fields from the literal, so a call that omitted one becomes a
+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.
@@ -13347,8 +14168,9 @@ from the root `stitchkit`.
 | `ScopedDefineContract` | _type_ | the `defineContract` `createContractFactory` returns — endpoint `scope` overrides join the union |
 | `ALL_TRANSPORTS` | constant | `['HTTP', 'MCP', 'AGENT', 'CLI']` |
 | `ContractDef` | _type_ | a defined contract |
+| `PathParams` | _type_ | infer named `:segments` and a terminal `*wildcard` from a path literal as string params |
 | `ContractMeta` | _type_ | a contract's `prefix` + optional `scope` and `meta` (a default every endpoint shallow-merges over) |
-| `EndpointDef` | _type_ | a single endpoint definition; `output` declares JSON response presence (`null` is data, `undefined` is invalid) |
+| `EndpointDef` | _type_ | a single endpoint definition; `output` declares JSON response presence (`null` is data, `undefined` is invalid); `safelistedBody: true` admits the JSON body as `text/plain` from an allow-listed `Origin` — [guide](../guide/server.md#safelisted-request-bodies-beacons) |
 | `EndpointStreamDescriptor` | _type_ | HTTP-only schema-derived stream declaration: item schema, envelope/item framing, stream-end/terminal completion, NDJSON/SSE encoding and frame/lifetime/heartbeat/idle bounds — [guide](../guide/server.md#contract-first-streams) |
 | `HeadEndpointDef` | _type_ | explicit HTTP-only, bodyless `HEAD` endpoint definition |
 | `EndpointResponseMeta` | _type_ | static success metadata declared by an HTTP-only typed-data endpoint |
@@ -13384,6 +14206,7 @@ from the root `stitchkit`.
 
 ### Errors
 
+| `ErrorVocabularyCode` / `ErrorVocabularyMapping` / `VocabularyCodeMap` | _type_ | application-code union, partial/exhaustive framework mapping input and resolved wire map returned by `defineErrors` |
 | Export | Kind | Summary |
 |--------|------|---------|
 | `AppError` | class | the framework error — `code` / `status` / `details` / `hint` |
@@ -13396,7 +14219,7 @@ from the root `stitchkit`.
 | `rateLimited` | function | throw `429 RATE_LIMITED` |
 | `appError` | function | throw an `AppError` for any code |
 | `defineErrors` | function | declare immutable domain error definitions → typed `AppError` constructors, codes and schemas — [guide](../guide/auth-and-errors.md#domain-errors--defineerrors) |
-| `DefinedErrors` | _type_ | the `{ errors, codes, definitions, isCode }` handle `defineErrors` returns |
+| `DefinedErrors` | _type_ | the `{ errors, codes, definitions, isCode, codeMap }` handle `defineErrors` returns |
 | `DefinedAppError` | _type_ | literal-code error instance with schema-refined details |
 | `ErrorDefinition` | _type_ | `{ status, message?, details? }` definition for one domain code |
 | `ErrorDefinitions` | _type_ | string-keyed domain error definition registry |
@@ -13552,7 +14375,7 @@ Also re-exports the error helpers from `stitchkit/contract`.
 | `composeLifecycleHooks` | function | compose HTTP lifecycle phases in declaration order with short-circuit/fallthrough semantics |
 | `AuthorizationContext` | _type_ | HTTP pre-body context with validated params, `input: undefined` and no files |
 | `RouteGroup` | _type_ | a prefixed group of services with its own hooks; matched errors try group `onError` → global `onError` → standard envelope, keeping the original error on fallback — [precedence](../guide/server.md#lifecycle-hooks) |
-| `RawRoute` | _type_ | a non-contract `Request → Response` route with a concrete `BunServer` context |
+| `RawRoute` | _type_ | a non-contract `Request → Response` route with a concrete `BunServer` context and optional stable `serviceName` / `action` observability identity |
 | `RawRouteContext` | _type_ | the Bun-bound routing context a raw handler receives |
 | `BunServer` | _type_ | the `Bun.serve` instance type |
 | `ServerPassthrough` | _type_ | extra `Bun.serve` options |
@@ -13569,7 +14392,8 @@ Also re-exports the error helpers from `stitchkit/contract`.
 |--------|------|---------|
 | `createAuthHook` | function | one scope gate for HTTP `authorize` and tool `beforeHandle` — [guide](../guide/auth-and-errors.md#createauthhook) |
 | `composeAuthHooks` | function | route multiple canonical auth domains by owned scope and atomically commit their typed contributions |
-| `createErrorHook` | function | an async-capable, endpoint-aware `onError` hook from a code map + envelope renderer — [guide](../guide/auth-and-errors.md#createerrorhook) |
+| `createErrorHook` | function | an async-capable, endpoint-aware `onError` hook from a `defineErrors` vocabulary or a code map, plus an envelope renderer — [guide](../guide/auth-and-errors.md#createerrorhook) |
+| `ErrorHookBase` / `ErrorHookMapping` | _type_ | common hook fields and the vocabulary-or-map branch accepted by `createErrorHook` |
 | `ErrorHookConfig` | _type_ | async observer/renderer config with partial `codeMap` and optional typed `unmappedCode` fallback |
 | `ResolvedError` | _type_ | the normalised error handed to `createErrorHook`'s `render` |
 | `createBearerResolver` | function | a bearer-token identity resolver |
@@ -13599,19 +14423,23 @@ Also re-exports the error helpers from `stitchkit/contract`.
 
 | Export | Kind | Summary |
 |--------|------|---------|
-| `defineCookie` | function | a typed cookie `get` / `set` / `clear` handle — [guide](../guide/auth-and-errors.md#cookies) |
-| `parseCookies` | function | parse a `Cookie` header to a record |
+| `defineCookie` | function | a typed cookie `get` / `getAll` / `set` / `clear` handle; `duplicates` names what `get` answers when two cookies share the name — [guide](../guide/auth-and-errors.md#cookies) |
+| `parseCookies` | function | parse a `Cookie` header to a record (the last of two same-named cookies wins) |
+| `parseCookieHeader` | function | parse a `Cookie` header to `[name, value]` pairs in header order, duplicates kept |
 | `serializeCookie` | function | build a `Set-Cookie` value |
 | `corsHeaders` | function | compute CORS response headers |
 | `corsPreflightResponse` | function | build a preflight `Response` |
 | `DEFAULT_CORS_ALLOW_HEADERS` | const | the default `Access-Control-Allow-Headers` (incl. `traceparent`) — extend it when overriding `cors.headers` |
-| `DEFAULT_CORS_EXPOSE_HEADERS` | const | the default `Access-Control-Expose-Headers` (incl. `Content-Disposition`, `ETag`, `Content-Range`) — extend it when overriding `cors.exposeHeaders` |
+| `DEFAULT_CORS_EXPOSE_HEADERS` | const | the default `Access-Control-Expose-Headers` (incl. `Content-Disposition`, `ETag`, `Content-Range`, `X-Build-Id`) — extend it when overriding `cors.exposeHeaders`, or a cross-origin page loses the build id |
 | `CookieDef` | _type_ | the `defineCookie` handle |
-| `CookieOptions` | _type_ | cookie attributes |
+| `CookieOptions` | _type_ | cookie attributes, plus the `duplicates` read policy |
+| `CookieDuplicatesPolicy` | _type_ | `'last'` (default) / `'first'` / `'reject'` — `reject` yields `undefined` for two different values and the value when they agree |
 | `CorsConfig` | _type_ | CORS policy |
 
 ### Realtime (server)
 
+| `bindSocketRegistry` | function | room membership and consistent replay over an already-authenticated realtime server |
+| `AuthorizedSocketRoom` / `SocketRegistry` / `SocketRegistryConnection` / `SocketRegistryOptions` / `SocketRegistryServer` / `SocketRegistrySnapshot` / `SocketReplayFrame` | _type_ | authorized room token, structural server boundary, replay frames and immutable registry state |
 | Export | Kind | Summary |
 |--------|------|---------|
 | `createSocketIOServer` | function | the typed Socket.IO server — [guide](../guide/realtime.md#server--createsocketioserver) |
@@ -13634,6 +14462,8 @@ Also re-exports the error helpers from `stitchkit/contract`.
 
 ### Primitives
 
+| `createFileStateStore` | function | cross-process locked atomic JSON state updates over one Zod schema |
+| `FileStateStoreCorruption` / `FileStateStoreOptions` | _type_ | explicit corrupt-state report/policy and lock timing configuration |
 | Export | Kind | Summary |
 |--------|------|---------|
 | `streamSSE` | function | an async generator → SSE `Response` — [guide](../guide/server.md#sse-streaming) |
@@ -13652,6 +14482,7 @@ Also re-exports the error helpers from `stitchkit/contract`.
 | `MultipartReceiver` | _type_ | consumer-owned Web-stream storage receiver |
 | `MultipartReceiverResult` | _type_ | receiver value plus rollback cleanup |
 | `StreamingMultipartImplementation` | _type_ | receiver registry and handler shape inferred by `defineMultipartStream` |
+| `bindReleaseRefreshSignal` / `ReleaseRefreshSignalOptions` / `ReleaseRefreshSignal` | function / _type_ | a deploy signal (`SIGUSR2`, the one user-defined signal the process vocabulary has) refreshes a `stitchkit/release` marker, whose subscribers tell every socket; never throws at the signal — [guide](../guide/release.md) |
 | `bindProcessSignals` | function | bind `SIGINT` / `SIGTERM` to one managed `shutdown()` — one chain, force on a later signal, default disposition on the one after — [guide](../guide/testing-and-deployment.md#process-signals--bindprocesssignals) |
 | `ProcessSignalsOptions` | _type_ | config for `bindProcessSignals` |
 | `ProcessSignalsBinding` | _type_ | the `{ promise, close }` handle `bindProcessSignals` returns |
@@ -13729,6 +14560,17 @@ cutovers are covered by the executable
 | Export | Kind | Summary |
 |--------|------|---------|
 | `createApplication` | function | compose a validated resource DAG into one startup, readiness, admission and shutdown state machine |
+| `StateStore` / `StateStoreUpdate` | _type_ | async atomic read/update boundary shared by durable application state machines |
+| `createProcessLifecycleLedger` / `ProcessLifecycleLedger` / `ProcessLifecycleLedgerConfig` | function / _type_ | durable bounded run history and typed fact subscription |
+| `LifecycleRunSchema` / `LifecycleRun` / `LifecycleStateSchema` / `LifecycleState` / `LifecycleTerminationSchema` / `LifecycleTermination` | schema / _type_ | versioned process-run state and termination vocabulary |
+| `PreviousExitSchema` / `PreviousExit` / `StartFact` / `ReadyFact` / `ShutdownFact` / `ProcessLifecycleFact` | schema / _type_ | first-boot, hot-reload, clean, forced, handoff and abnormal lifecycle facts |
+| `transitionProcessStart` / `transitionProcessReady` / `transitionProcessShutdown` | function | pure idempotent runId+pid-owned transitions |
+| `LifecycleTransition` / `TransitionStartInput` / `TransitionReadyInput` / `TransitionShutdownInput` / `SameVersionOverlap` | _type_ | pure transition inputs, the same-build overlap policy (`abnormal` default / `handoff`) and state+fact result |
+| `lifecycleLedgerResource` / `LifecycleLedgerResource` / `LifecycleLedgerResourceConfig` | function / _type_ | managed-resource adapter that records start, readiness and shutdown |
+| `createNotificationOutbox` / `NotificationOutbox` / `NotificationOutboxConfig` | function / _type_ | bounded at-least-once queue with durable claims, leases, retries and supersede |
+| `NotificationOutboxItem` / `NotificationOutboxReceipt` / `NotificationOutboxState` / `NotificationSend` / `NotificationFailureClassification` / `DroppedNotification` / `EnqueueNotification` | _type_ | versioned queue records, stable send identity and delivery decisions |
+| `notificationOutboxStateSchema` | function | strict persisted-state schema over an application payload schema |
+| `notificationOutboxResource` / `NotificationOutboxResource` / `NotificationOutboxResourceConfig` | function / _type_ | thin managed-resource scheduler over an outbox handle |
 | `ApplicationHandle.restart` | method | replace one resource and everything that depends on it, leaving the rest of the graph running and the process epoch unchanged |
 | `ApplicationRestartInputSchema` / `ApplicationRestartInput` | schema / _type_ | the resource to replace, by id, and optionally `gracePeriodMs` / `forceTimeoutMs` for this restart — the application's own shutdown budget otherwise |
 | `ApplicationRestartResultSchema` / `ApplicationRestartResult` | schema / _type_ | the subtree that was actually taken down and brought back, in start order, with the outcome, the reason on anything but success, and how long it took |
@@ -13775,6 +14617,19 @@ cutovers are covered by the executable
 | `BoundedAdmissionRefusalError` | class | `run()` refusal with reason and optional `retryAfterMs` |
 | `BoundedOperationWaitError` | class | caller wait ended as `cancelled` or `timed-out`; underlying capacity remains leased until work settles |
 
+### Revision wake-up
+
+| Export | Kind | Summary |
+|--------|------|---------|
+| `createRevisionSignal` | function | finite broadcast wait for the next monotonic process-local revision |
+| `RevisionSignal` / `RevisionSignalConfig` / `RevisionSignalClock` / `RevisionSignalTimer` | _type_ | signal handle, waiter bound and replaceable timer boundary |
+| `RevisionSignalWaitOptions` | _type_ | optional caller `signal` and positive `timeoutMs`; absent options wait until advance or close |
+| `RevisionSignalWaitOutcomeSchema` / `RevisionSignalWaitOutcome` | schema / _type_ | `changed \| timed-out \| aborted \| closed \| capacity` |
+| `RevisionSignalWaitResultSchema` / `RevisionSignalWaitResult` | schema / _type_ | terminal wait outcome with the revision observed at settlement |
+| `RevisionSignalAdvanceResultSchema` / `RevisionSignalAdvanceResult` | schema / _type_ | successful `advanced` or post-close `closed`, with the resulting revision |
+| `RevisionSignalStateSchema` / `RevisionSignalState` | schema / _type_ | `open \| closed` lifecycle |
+| `RevisionSignalSnapshotSchema` / `RevisionSignalSnapshot` | schema / _type_ | current revision, finite pending count and lifetime outcome counters |
+
 ### Bounded delivery
 
 | Export | Kind | Summary |
@@ -14354,6 +15209,11 @@ audit event. See the [Observability guide](../guide/observability.md).
 | Export | Kind | Summary |
 |--------|------|---------|
 | `createObservability` | function | configure framework-owned request completion and canonical tool event sinks — [guide](../guide/observability.md#createobservability) |
+| `createDimensionsProjector` / `DimensionsProjector` / `DimensionsProjectorConfig` / `ProjectedDimensions` | function / _type_ | typed request/result/error attribution projected into the existing request context |
+| `DimensionCollision` / `SetRequestDimensionsOptions` | _type_ | explicit overwrite, preserve or error policy for dimension keys |
+| `createBoundedLogger` | function | decorate a `StitchLogger` with request context, shared sanitisation, redaction and total bounds |
+| `DEFAULT_REDACT_PATHS` | constant | baseline credential/token paths added to the sanitizer's sensitive-key policy |
+| `BoundedLoggerBounds` / `BoundedLoggerOptions` | _type_ | per-value and total record ceilings plus sink/redaction configuration |
 | `RequestEvent` | _type_ | the normalised audit event handed to the sink; opt-in HTTP cancellation rows carry `outcome: 'cancelled'` |
 | `ObservabilityConfig` | _type_ | independent request and tool sink configuration |
 | `Observability` | _type_ | `{ request?, toolCall, getStatus(), flush(), close() }` with bounded sink lifecycle |
@@ -14774,6 +15634,97 @@ injected grammY bot. → ADR 0143
 
 ---
 
+## `stitchkit/tracking`
+
+Browser-safe visitor-tracking mechanics, with no event vocabulary of their own
+and no React. The React wrapper (a provider and a hook, ~40 lines) is the
+application's — it owns the router and the session. The server half is
+`stitchkit/tracking/server`. → ADR 0166 — [guide](../guide/tracking.md)
+
+| Export | Kind | Summary |
+|--------|------|---------|
+| `createTrackingClient` | function | the client: visit lease and renewal, pending queue, synchronous identity from reserved sequences, outbox and flush lease, delivery, the string-body page-leave beacon plus a queued copy, visible time, scroll milestones, declarative clicks, heartbeats |
+| `TrackingClient` / `TrackingClientConfig` | _type_ | `track` / `onNavigate` / `start` / `visitId` / `browserStreamId` / `attribution`, and the host, `buildId`, `builtin` names, `bootstrap`, `deliver`, optional `decorate` (your `eventExtras` on every minted event), `unload` / `unloadUrl`, `outbox`, `onUnauthorized`, `onVisit`, `onFailure`, `isAction`, `referrerMap`, `clickAttributes`, `scrollMilestones`, `batchSize`, periods and limits |
+| `TrackFn` / `EventsWithMetadata` / `EventsWithoutMetadata` | _type_ | `track(type)` / `track(type, metadata)` typed by the application's metadata map, and the two halves of that map |
+| `BuiltinTrackingEventTypes` / `CONVENTIONAL_TRACKING_EVENT_TYPES` | _type_ / const | the application's names for the events the client emits itself; the conventional `PAGE_VIEW` … `INTERACTION` set |
+| `browserTrackingHost` / `TrackingHost` / `TrackingPageContext` | function / _type_ | everything the client takes from a browser tab behind one interface — page context, visibility, scroll depth, events, intervals, clocks, storage — so a test or a non-tab host can supply its own |
+| `createTrackingContract` / `TrackingContractConfig` / `TrackingContractEndpoints` | function / _type_ | `bootstrap` (`POST /visit`) and `track` (`POST /events`, `safelistedBody`) from the application's event types, scope and optional extras |
+| `createTrackingSchemas` / `TrackingSchemas` / `TrackingSchemasConfig` | function / _type_ | every schema of one surface — `event`, `request`, `response`, `disposition`, `entry`, `bootstrap` — from `eventTypes`, optional `eventExtras`, `buildIdPattern`, `maxEventsPerBatch` |
+| `TrackingEventEnvelope` / `TrackingEventShape` | _type_ | `eventId`, `visitId`, `browserStreamId`, `browserSequence`, `type`, `page`, `metadata`, `clientTimestamp` |
+| `TrackEventsRequest` / `TrackEventsResponse` / `TrackEventsResponseSchema` | _type_ / schema | a batch (`buildId`, `events`, `utm`) and its answer (`accepted`, `dispositions`) |
+| `TrackingDisposition` / `TrackingDispositionSchema` / `TrackingDispositionStatus` / `TrackingDispositionStatusSchema` | _type_ / schema | `accepted` / `duplicate` / `identity-invalid` / `excluded-bot` — every one terminal |
+| `VisitEntryContext` / `VisitEntryContextShape` / `VisitBootstrapResponse` / `VisitBootstrapResponseSchema` | _type_ / schema | what a browser reports to open a visit (lineage, landing, referrer, UTM, display, screen, `buildId`, outbox health) and the lease it gets back |
+| `TrackingOutboxState` / `TrackingOutboxStateSchema` | _type_ / schema | `available` / `unavailable` |
+| `UtmData` / `UtmDataSchema` / `AttributionData` / `AttributionDataSchema` | _type_ / schema | campaign tags and a touch (UTM, referrer, landing page) |
+| `DEFAULT_BUILD_ID_PATTERN` | const | `dev` or a git SHA |
+| `createTrackingOutbox` / `TrackingOutbox` / `TrackingOutboxOptions` / `TrackingOutboxHealth` | function / _type_ | the tab-shared outbox: `streamId`, `reserveSequences`, `enqueue`, `acquireLease` / `releaseLease` (short, released on leave), `readBatch`, `acknowledge`, `health`; bounded by count and age |
+| `TrackingOutboxStorage` / `TrackingOutboxMeta` / `TrackingOutboxEvents` / `TrackingOutboxRecord` / `TrackingQueuedEvent` | _type_ | one atomic, all-or-nothing `transact` over a key/value store and an event store (`readonly` for pure reads) — the contract an adapter implements |
+| `indexedDbOutboxStorage` / `memoryOutboxStorage` | function | the IndexedDB adapter (one `readwrite` transaction per `transact`) and the in-memory one for tests and degraded mode |
+| `createSequenceReserve` / `SequenceReserve` / `SequenceReserveOptions` | function / _type_ | a block of reserved numbers spent synchronously — `take` / `refill` / `shared` — with a per-tab fallback when the source fails |
+| `deliverTrackingBatch` / `TrackingDeliveryOptions` / `TrackingDeliveryOutcome` | function / _type_ | one batch, one bounded retry on `0` / `5xx`; `delivered` / `failed` / `auth-invalidated` (on `401` / `403`) with an optional `onUnauthorized` recovery |
+| `sendUnloadBeacon` | function | `sendBeacon` with a **string** body — the `text/plain` request a dying document can still complete; `false` without the API |
+| `createVisibleTimeMeter` / `VisibleTimeMeter` / `VisibleInterval` / `VisibleHeartbeat` / `VisibleTimeMeterOptions` | function / _type_ | additive visible time — `checkpoint` / `cut` / `heartbeat`, each interval with its own id; a hidden heartbeat carries no interval |
+| `scrollDepthPercent` / `createScrollMilestones` / `ScrollMilestones` | function / _type_ | depth as a percentage of the scrollable range; milestones fired once each per page |
+| `createOncePerPage` / `OncePerPage` | function / _type_ | one fact per key per page within a window — the guard a twice-mounted component cannot keep itself |
+| `resolveAttribution` / `ResolveAttributionInput` / `ResolvedAttribution` / `AttributionStorage` / `ReferrerRule` | function / _type_ | first-touch once, current-touch on every new UTM; the referrer → source/medium map is the application's, there is no built-in list |
+| `parseUtmFromSearch` / `parseReferrer` | function | the two parsers `resolveAttribution` is built from |
+| `resolveTrackedClick` / `ResolveTrackedClickOptions` / `TrackedClick` / `TrackedClickAttributes` / `ClickTarget` | function / _type_ | `data-track` → click, `data-track-action` → interaction, a link to another origin → outbound; attribute names configurable; `leavesPage` says which path to send on |
+
+---
+
+## `stitchkit/tracking/server`
+
+The decisions a tracking backend makes, without the storage it makes them
+over. The application reads visits and stored hashes from its database, hands
+them here and writes what comes back; `issueVisitLease` runs the visit
+algorithm over a store the application implements. → ADR 0166
+
+| Export | Kind | Summary |
+|--------|------|---------|
+| `dispositionTrackingBatch` / `DispositionInput` / `DispositionResult` / `DispositionEvent` / `KnownVisit` | function / _type_ | decide a batch: bot → all `excluded-bot`; wrong lineage or owner → `identity-invalid`; stored id → `duplicate` (+ `conflicts` when the hash differs); rest `accepted`; anonymous visits an identified caller may `adopt` |
+| `issueVisitLease` / `IssueVisitLeaseOptions` / `IssuedVisitLease` | function / _type_ | under the lineage lock: continue the named or latest active visit (adopting an anonymous one when `ownership: 'adopting'`), else end what is open and start a new one; a bot gets a lease no store holds |
+| `TrackingVisitStore` / `FindActiveVisitQuery` / `ActiveVisit` / `VisitActor` / `VisitOutboxHealth` / `VisitOwnership` | _type_ | the six-method store the application implements over its database — `withLineageLock`, `findActive`, `touch`, optional `adopt`, `endOpen`, `create` — and the shapes it exchanges |
+| `activeIntervalOf` / `ActiveTimeInterval` / `ActiveIntervalOptions` | function / _type_ | the visible-time interval an event carries, dated by the server clock; `null` for an unshaped or implausible one |
+| `hashTrackingEvent` | function | `sha256(JSON.stringify(parsedEvent))` — the stored payload hash, unsorted on purpose so it matches what applications already hold |
+| `isBotUserAgent` / `DEFAULT_BOT_USER_AGENT_PATTERN` | function / const | crawlers, monitors and `headlesschrome` are not visitors |
+| `createPresenceRegistry` / `PresenceRegistry` / `PresenceEntry` | function / _type_ | who is here now, in this process: `touch` / `snapshot(filter)` / `presentVisitOf` with a 45 s TTL |
+
+---
+
+## `stitchkit/release`
+
+A page follows the release it was built for. The server keeps a marker of the
+current frontend build and names it on every response (`X-Build-Id`) and every
+socket connection; the browser compares that to its **own** build id and
+reloads under a declared policy. Reading the build id and sending the deploy
+signal stay with the application. → ADR 0167 — [guide](../guide/release.md)
+
+| Export | Kind | Summary |
+|--------|------|---------|
+| `createReleaseMarker` / `ReleaseMarker` / `ReleaseMarkerConfig` / `ReleaseRefresh` | function / _type_ | `current()`, `refresh()` → `{ changed, buildId }`, `subscribe`; built on an application `read` that returns `null` where there is no release; a bad value or a throwing subscriber goes to `onError`, never out |
+| `RELEASE_HEADER` | const | `X-Build-Id` — set on every response of a handler configured with `release`, exposed through CORS by default |
+| `createReleaseWatcher` / `ReleaseWatcher` / `ReleaseWatcherConfig` / `ReleaseReloadPolicy` | function / _type_ | `observe(buildId)` against the bundle's own id; `immediate` / `when-hidden` / `on-navigation` with `maxDeferMs`; one reload per id, remembered across it; `navigated`, `stale`, `dispose`, `onStale` |
+| `browserReleaseHost` / `ReleaseWatcherHost` | function / _type_ | visibility, timer and reload behind one interface — a test supplies its own |
+| `bindReleaseToSocketServer` / `observeReleaseFromSocket` | function | the socket channel: each connection re-reads and hears the build, everyone hears a change; the client hands the event to the watcher |
+| `ReleaseSocketServer` / `ReleaseSocketEmitter` / `ReleaseSocketListener` / `ReleaseSocketOptions` | _type_ | the structural slices of a Socket.IO server and client the bindings use — no peer import |
+
+---
+
+## `stitchkit/geo`
+
+Server-only managed GeoIP generations. Applications own database acquisition,
+licensing and domain mapping; the optional MaxMind peer is loaded only when its
+adapter is used.
+
+| Export | Kind | Summary |
+|--------|------|---------|
+| `createGeoIpResolver` / `GeoIpResolver` / `GeoIpResolverOptions` / `GeoIpSnapshot` | function / _type_ | public-IP lookup over one stable reader generation; unavailable start, last-known-good degraded reload and cleanup are explicit states |
+| `createMaxMindGeoIpLoader` / `MaxMindGeoIpLoaderOptions` / `MaxMindGeoIpPaths` | function / _type_ | lazy optional-peer City+ASN loader with stable before/after file revision checks |
+| `GeoIpReader` / `GeoIpReaderLoader` | _type_ | peer-neutral reader/generation seam for adapters and tests |
+| `GeoAttribution` / `mapGeoIpRecord` | _type_ / function | generic optional place and autonomous-system projection; application-specific fields remain outside |
+
+---
+
 ## `stitchkit/declaration`
 
 Zod-only, dependency-free. The **project declaration**: the single
@@ -14866,7 +15817,7 @@ runtime-agnostic pieces of `stitchkit/server` and the error helpers.
 | `NodeServerHandle` | _type_ | managed Node handle (`url`, `port`, `runtime`, `status`, `shutdown`) |
 | `NodeRuntimeServer` | _type_ | concrete `srvx/node` runtime escape hatch |
 | `NodeSocketLifecycle` | _type_ | Bun-free Socket.IO lifecycle accepted by `serveNode` |
-| `HandlerConfig` / `ServiceDef` / `RawRoute` / `RawRouteContext` | _type_ | runtime-neutral handler types; raw routes default their host server to `unknown` |
+| `HandlerConfig` / `ServiceDef` / `RawRoute` / `RawRouteContext` | _type_ | runtime-neutral handler types; raw routes default their host server to `unknown` and may declare stable `serviceName` / `action` observability identity |
 | `SocketIORequestPolicy` / `SocketIOServerConfig` / `SocketIOPeerLoaders` / `SocketIOServerHandle` | _type_ | runtime-neutral handshake policy, config, optional-peer loaders and the Bun-free Node handle with `io`, `attach` and lifecycle |
 | `UnixClientTransportConfig` / `UnixClientTransport` | _type_ | Unix socket bounds, explicit response-body mode and owned Fetch-compatible handle |
 | `UnixResponseBodyMode` | _type_ | finite cumulative `bounded` mode or explicit pull-driven `streaming` mode |
@@ -14909,12 +15860,14 @@ SDK nor the `ai` peer.
 
 ## `stitchkit/react`
 
-Browser-only. The React data-layer helpers. Needs the `@tanstack/react-query`
-and `react-query-kit` peers.
+Browser- and server-render-safe React data-layer helpers. Needs the
+`@tanstack/react-query` and `react-query-kit` peers.
 
 | Export | Kind | Summary |
 |--------|------|---------|
 | `createCursorQuery` | function | a cursor-paginated infinite query — [guide](../guide/client.md#cursor-pagination) |
+| `apiErrorRetry` | function | build a bounded network/HTTP-status retry predicate using cross-bundle `ApiError.is` — [guide](../guide/react.md#api-error-retries) |
+| `createQueryClientFactory` | function | request-local SSR QueryClient through a supplied cache adapter plus a factory-local browser singleton — [guide](../guide/react.md#query-client-per-runtime) |
 | `createCacheBridge` | function | sync socket events into the Query cache — [guide](../guide/realtime.md#cache-bridge) |
 | `createRealtimeCacheBridge` | function | the same bridge fed by a **validated realtime contract**; the payload comes from the contract's args tuple instead of inferring `never` |
 | `createEntityCacheHandlers` | function | created/updated/deleted cache handlers for one entity — [guide](../guide/realtime.md#entity-cache-handlers) |
@@ -14928,6 +15881,9 @@ and `react-query-kit` peers.
 | `EntityCacheListShape` | _type_ | `array \| paginated \| infinite-array \| infinite-paginated` |
 | `DeletedPayload` | _type_ | a `deleted` event payload — the entity or a bare `{ id }` |
 | `CursorQueryConfig` | _type_ | config for `createCursorQuery` |
+| `ApiErrorRetryConfig` | _type_ | retry attempts, excluded application codes, inclusive status ranges and network policy |
+| `QueryClientFactoryConfig` / `QueryClientServerCache` | _type_ | TanStack config, mutation observer, retry policy and request-cache adapter |
+| `QueryRetryValue` | _type_ | TanStack's accepted query retry value retained by the factory pass-through |
 | `CacheBridge` | _type_ | the `createCacheBridge` handle |
 | `CacheBridgeConfig` | _type_ | config for `createCacheBridge` |
 | `RealtimeCacheBridgeConfig` | _type_ | config for `createRealtimeCacheBridge` — same fields, a `ValidatedRealtimeSocket` in place of the raw socket |