stitchkit 0.118.0 → 0.119.0

package/llms/upgrading.txt

@@ -11,11 +11,11 @@ Contains: Guide: Upgrading, general  (docs/guide/upgrading.md)
 
 Load this slice, then every range slice between your installed version and the target:
 
-- 0.105.0 → 0.118.0: `llms/upgrading-0.105.0-0.118.0.txt`
-- 0.84.0 → 0.104.0: `llms/upgrading-0.84.0-0.104.0.txt`
-- 0.63.0 → 0.83.0: `llms/upgrading-0.63.0-0.83.0.txt`
-- 0.44.0 → 0.62.0: `llms/upgrading-0.44.0-0.62.0.txt`
-- 0.37.0 → 0.44.0: `llms/upgrading-0.37.0-0.44.0.txt`
+- 0.106.0 → 0.119.0: `llms/upgrading-0.106.0-0.119.0.txt`
+- 0.96.0 → 0.105.0: `llms/upgrading-0.96.0-0.105.0.txt`
+- 0.69.0 → 0.95.0: `llms/upgrading-0.69.0-0.95.0.txt`
+- 0.55.0 → 0.68.0: `llms/upgrading-0.55.0-0.68.0.txt`
+- 0.37.0 → 0.53.0: `llms/upgrading-0.37.0-0.53.0.txt`
 
 # Upgrading stitchkit
 

package/llms-full.txt

@@ -78,16 +78,17 @@ own, recorded as an ADR.
 | `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/voice` | browser **and** server | evolving | the mechanics of a live voice reply — `SentenceCutter`, `speakableText`, a `SpeechQueue` that synthesises ahead and stops on interruption, the conversation phases |
 | `stitchkit/geo` | server (Bun or Node) | evolving | managed GeoIP reader generations, last-known-good reload and the optional MaxMind adapter |
+| `stitchkit/geo/contract` | browser **and** server | evolving | the place snapshot schema, for a shared contract that stores or sends `GeoAttribution`; brings `zod` |
 | `stitchkit/xlsx` | browser **and** server | evolving | a workbook from rows and typed columns, with no dependency; text never runs as a formula |
 | `stitchkit/oauth` | browser **and** server | evolving | provider-neutral Authorization Code + PKCE request and one-shot callback transaction mechanics |
 | `stitchkit/google` | server (Bun or Node) | evolving | optional Google code exchange and verified OIDC identity adapter |
-| `stitchkit/observability` | server | stable<br>_redefined in 2 of the 63 minors since 0.56.2, most recently 0.92.0_ | request/tool event projections — `createObservability`, trace context, sanitisation |
+| `stitchkit/observability` | server | stable<br>_redefined in 2 of the 64 minors since 0.56.2, most recently 0.92.0_ | 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, the managed-resource conformance kit and manual time for schedules and retries |
 | `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 + server rendering | stable | `createCursorQuery`, `createCacheBridge`, QueryClient and `ApiError` retry policy |
 | `stitchkit/react/keyboard` | browser | evolving | which part of a screen gets a key — ordered layers, one Escape per level, list zones with real focus; see [keyboard guide](keyboard.md) |
 | `stitchkit/react/keyboard/testing` | server (Bun or Node) | evolving | the keyboard layers and zones without a DOM — fakes for the window, elements and key events beside the two engines, to test the order of layers, `scope`/`inert` and the edges of a zone in milliseconds |
-| `stitchkit/agent-runtime` | server | evolving<br>_redefined in 25 of the 63 minors since 0.56.2, most recently 0.115.0_ | optional durable conversation/run loop, history, models, prompts, fencing and events |
+| `stitchkit/agent-runtime` | server | evolving<br>_redefined in 25 of the 64 minors since 0.56.2, most recently 0.115.0_ | optional durable conversation/run loop, history, models, prompts, fencing and events |
 | `stitchkit/agent-runtime/sandbox` | server | evolving | optional Linux Bubblewrap sessions, durable workspaces and a host HTTP credential gateway; see [sandbox guide](sandbox.md) |
 | `stitchkit/agent-runtime/testing` | tests on Bun or Node | evolving | credential-free replay, scripted provider faults, deterministic race controls and the agent-store conformance kit |
 | `stitchkit/agent-runtime/harness` | server | evolving | resource-aware process-local facade over the canonical Agent runtime; supervision stays outside |
@@ -99,7 +100,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 14 of the 63 minors since 0.56.2, most recently 0.110.0_ | managed resource graph, readiness, admission, schedules, subtree restart and bounded shutdown |
+| `stitchkit/application` | browser + server | evolving<br>_redefined in 14 of the 64 minors since 0.56.2, most recently 0.110.0_ | managed resource graph, readiness, admission, schedules, subtree restart and bounded shutdown |
 | `stitchkit/application/grammy` | server | evolving | a grammY bot as application resources — configuration, then polling with updates admitted by batch — and the webhook adapter |
 | `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 |
@@ -445,7 +446,7 @@ Both entrypoints are **evolving**.
 | 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 |
+| visible time, scroll milestones, `data-track` clicks, raw first/current touch | channel classification, click-marker names, the attribute names |
 | `dispositionTrackingBatch`, `issueVisitLease`, `activeIntervalOf`, presence | the tables, the transaction, adoption, geo, reports |
 
 ## Contract
@@ -492,7 +493,7 @@ const client = createTrackingClient<BrowserEvents>({
   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' }],
+  clickIdParams: ['gclid', 'gbraid', 'wbraid', 'msclkid', 'yclid', 'ttclid', 'fbclid'],
   isAction: isInteractionAction,
   onVisit: (visitId) => rum.setVisit(visitId),
 })
@@ -505,6 +506,28 @@ client.track('ITEM_VIEW', { itemId, itemTitle })
 client.track('SIGN_OUT')
 ```
 
+Attribution carries observations, not a channel verdict. `utm` contains only the current URL's
+`utm_*` parameters, retaining case and whitespace up to 200 characters per field; tags without
+`utm_source` are valid. Parameter names are case-sensitive (`UTM_SOURCE` is not a tag), a repeated
+tag keeps its first value, and a whitespace-only value is kept as the fact it is. `referrer` carries
+the referring URL with credentials masked. Neither an external referrer nor a click marker creates
+campaign tags. Classify the channel on your server.
+
+Attribution belongs to the visit: the bootstrap entry carries it, and an event batch carries events
+only. Join events to their visit on the server to attribute them.
+
+`clickIdParams` is the application's ordered list of query-parameter names to recognise. There is no
+built-in list: the first configured name with a nonempty value becomes `clickId` in the touch and
+bootstrap entry. Only the name is retained, never the click ID's value: a referrer from your own site
+repeats the landing query, so the value of every configured marker in a referrer is masked too. An empty
+list collects none; names must contain 1–200 characters, and `createTrackingClient` refuses a list that
+does not. Bootstrap collects these facts even if browser storage is unavailable.
+
+`client.attribution()` returns `firstTouch` and `currentTouch`. The first is persisted for 90 days
+by default; the current is this capture's raw context, so an untagged page does not inherit an earlier
+campaign. The server owns any policy for retaining the last non-direct channel. Stored first-touch
+records carry a format version; unversioned attribution is discarded because its tags may be inferred.
+
 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
@@ -895,33 +918,55 @@ tools. Narrow it with `expose`:
 
 - `expose: ['HTTP']` — HTTP only. The endpoint never becomes a tool.
 - `expose: ['MCP', 'AGENT']` — a tool only; no HTTP route.
-- omit `expose` — all transports.
+- `expose: []` — no transport; the endpoint stays hidden.
+- omit `expose` — HTTP, MCP and AGENT; CLI is opt-in.
 
-For a curated or security-sensitive tool surface, opt into explicit tool
-exposure at the scoped factory:
+Choose an application's default surface at its scoped factory. Scope and policy
+are inferred in separate calls, so the returned endpoint types retain exact transports:
 
 ```ts
-const { defineContract } = createContractFactory<AppScope>({
-  toolExposure: 'explicit',
+const { defineContract } = createContractFactory<AppScope>().configure({
+  toolExposure: { default: ['HTTP', 'CLI'] },
 })
 ```
 
-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.
+An omitted `expose` (including `undefined`) materializes this array on the returned
+endpoint before validation. An explicit endpoint array **replaces** it, never merges
+with it: `['HTTP']` stays HTTP-only, `['MCP']` enables only MCP, and `[]` hides the
+operation everywhere. Types, HTTP routes, typed clients, tools, CLI, OpenAPI and
+transport summaries read that same materialized exposure.
+
+HTTP client methods and URL builders require a **guaranteed** HTTP transport:
+pass a literal policy array directly to `configure` so its const generic infers
+the tuple. A stored array, even with `satisfies ContractFactoryConfig`, can widen
+to `Transport[]` and contain no HTTP at runtime,
+so it does not promise an HTTP method. Optional capabilities preserve both
+possible effective exposures rather than claiming an unfiltered default tuple.
+
+The same holds for an endpoint whose own type is broad, with or without a factory:
+a value annotated as `EndpointDef` or `FactoryScopedEndpoint<Scope>` carries
+`expose?: readonly Transport[]`, which may hold no HTTP, so it has no client method
+or URL. A helper that builds endpoints keeps their literal type with a const generic:
+
+```ts
+const endpoint = <const Endpoint extends FactoryScopedEndpoint<AppScope>>(value: Endpoint) => value
+```
 
-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.
+For a curated tool surface use `toolExposure: { default: ['HTTP'] }`, then name
+tool transports only on endpoints that intentionally join them. An empty default
+is legal. Each `configure` snapshots its array independently; it does not change
+the base factory, sibling configurations or authored endpoints. The no-config
+factory and plain `defineContract` keep the default-on behaviour above.
 
-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
-a tool result cannot carry — it would serialize to `{}`),
-[`responseMeta`](./server.md#typed-json-response-metadata) (outbound HTTP
-headers have no meaning on a tool call) and `rawBody` (HTTP-only by
-construction).
+Six intrinsic HTTP-only forms intersect an **implicit factory default** with HTTP:
+`multipart`, [`rawResponse`](./server.md#raw-response-endpoints),
+[`responseMeta`](./server.md#typed-json-response-metadata), `rawBody`, streaming
+responses and `HEAD`. Under `['HTTP', 'CLI']` they receive `['HTTP']`; under
+`['CLI']` or `[]` they receive `[]`, not an implicitly reopened HTTP route.
+An **explicit** non-HTTP exposure on any of them is a definition error, not a
+silent downgrade. `safelistedBody` only changes HTTP parsing and remains
+multi-transport. A factory policy applies only to contracts authored through
+that factory, not to contracts another helper builds internally.
 
 ## Tool options (`tool`)
 
@@ -939,7 +984,7 @@ endpoint that can never be a tool (a raw response, a stream, `responseMeta`,
 
 `expose` stays outside the group: it chooses transports, HTTP included.
 Setting `tool` on an endpoint with no tool transport — `expose: ['HTTP']`, or an
-omitted `expose` under a factory with `toolExposure: 'explicit'` — throws at
+omitted `expose` under a factory with a default containing no tool transport — throws at
 definition time. The pre-0.94 top-level keys (`toolName`, `toolView`, `ui`,
 `annotations`, `mcp`) are refused by name, with where each one went.
 
@@ -2236,11 +2281,24 @@ contract route does.
 
 ### Serving files & Range requests
 
-`staticRoute` is basic on purpose — it reads the whole file into memory and has
-no `Range` or conditional support; put a CDN in front, or use it for small web
-assets. To serve **media** (video / audio / large downloads) that a browser must
-seek and cache, use **`serveFile`** (Bun) — it streams the requested byte range
-and speaks the conditional-request half of RFC 7233 / 9110:
+`staticRoute(prefix, dir, { cacheControl })` serves a directory: it checks
+containment, then answers the file through `serveFile`, so a static image or
+video carries `ETag`, `Last-Modified` and `Accept-Ranges`, revalidates to `304`
+and seeks with `206`. `cacheControl` sets `Cache-Control` on every answer; by
+default none is sent.
+
+```ts
+import { createServer, staticRoute } from 'stitchkit/server'
+
+createServer({
+  rawRoutes: [staticRoute('/static', './public', { cacheControl: 'public, max-age=3600' })],
+})
+```
+
+The route answers `GET`. To serve a file chosen by your own logic — through a
+contract, with `HEAD`, a download name or a custom type — call **`serveFile`**
+directly. It runs on Bun and Node, streams the requested byte range and speaks
+the conditional-request half of RFC 7233 / 9110:
 
 ```ts
 import { defineContract } from 'stitchkit/contract'
@@ -2290,7 +2348,7 @@ emit none.
 `serveFile` takes an explicit `path` and trusts it — **the caller owns
 containment**. For a URL-derived path use `staticRoute` (which enforces it) or
 `isWithinDir` first. The byte-range parser is exported on its own as
-`parseByteRange(header, size)` for direct use and testing. → ADR 0023.
+`parseByteRange(header, size)` for direct use and testing. → ADR 0023, ADR 0281.
 
 ## Server primitives
 
@@ -4866,8 +4924,8 @@ export const users = defineContract({ prefix: 'users' }, {
   reshapes values inside the full schema. With `output` alone it is a slice, and
   the full result must fit that schema — `withToolView` refuses the endpoint at
   compile time when it does not.
-- **Exposure.** A view needs a tool transport. With `createContractFactory({
-  toolExposure: 'explicit' })` an endpoint without `expose` is HTTP-only, so an
+- **Exposure.** A view needs a tool transport. With `createContractFactory<Scope>().configure({
+  toolExposure: { default: ['HTTP'] } })` an endpoint without `expose` is HTTP-only, so an
   endpoint with a view names its tool transports in `expose`.
 - **What it refuses.** `defineContract` rejects a view on an endpoint with no
   tool transport or no full `output`, on a raw, `rawBody`, multipart,
@@ -15141,9 +15199,9 @@ Notes for a Node host:
 - **Socket.IO** attaches to the Node HTTP server via `serveNode({ socket })`, and
   on Node the default transport is `['websocket']` — set the client to match
   (`transports: ['websocket']`). See [realtime](./realtime.md).
-- **Bun-only helpers** do not run on Node: `serveFile` (uses `Bun.file`) and the
-  raw WebSocket lane. `staticRoute` is runtime-neutral (`node:fs`) and works on
-  both, but in production prefer a CDN / the static front-end below.
+- **Bun-only helpers** do not run on Node: the raw WebSocket lane. `serveFile`
+  and `staticRoute` work on both — on Node the body is a `node:fs` read stream —
+  but in production prefer a CDN / the static front-end below.
 
 ### Production checklist
 
@@ -16937,7 +16995,45 @@ 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.
+is a sparse `GeoAttribution`: absent facts have no own property, not `null` or
+an own `undefined` value. City and ASN can be present independently. The default
+mapper preserves the complete City + ASN place snapshot:
+
+| Fields | Meaning |
+|--------|---------|
+| `continentCode`, `continentName`, `continentGeonameId` | continent code, English name and GeoNames identifier |
+| `countryCode`, `countryName`, `countryGeonameId` | the country the database locates the address in; absent when the record locates none |
+| `registeredCountryCode`, `registeredCountryName`, `registeredCountryGeonameId` | the country the address block is registered to, a separate fact |
+| `regionCode`, `regionName`, `regionGeonameId` | first subdivision |
+| `city`, `cityGeonameId`, `postalCode` | city and postal facts; no city is required |
+| `latitude`, `longitude`, `timezone`, `accuracyRadiusKm` | coordinates, timezone and accuracy radius in kilometres; zero is a value |
+| `autonomousSystemNumber`, `autonomousSystemOrganization` | finite autonomous system number and organisation |
+| `localizedNames` | every available language under optional `continent`, `country`, `registeredCountry`, `region` and `city` dictionaries |
+
+No locale is synthesised: without English names, localized dictionaries make a
+meaningful result, but `countryName`, `regionName` or `city` stays absent. The
+located country is never inferred from the registered one — an application that
+wants a country for every address chooses `countryCode ?? registeredCountryCode`
+itself, knowing which fact it used. Empty localized groups are omitted. Each field
+is validated on its own by the schema: text is nonempty, GeoNames identifiers and
+`accuracyRadiusKm` are nonnegative safe integers, latitude and longitude are in
+range. A malformed field is omitted without erasing the other valid facts. Unknown
+vendor fields are not projected.
+
+A snapshot carries every language the database has: with the eight GeoLite2
+languages in all five groups it is 1–1.5 KB of JSON. An application that stores
+one per visit and needs fewer languages maps the result to its own shape.
+
+`GeoAttributionSchema` is the strict, readonly Zod owner of the DTO. It lives in
+the browser-safe `stitchkit/geo/contract`, so a shared contract validates a stored
+or transported snapshot without the server-only resolver. Every field is optional
+and readonly; use `.unwrap()` before composing the underlying object schema. The
+mapper copies localized dictionaries, so later reader mutations do not change a
+snapshot. An empty or unrecognised record returns `null`.
+
+An explicit `map` callback receives the raw reader result and owns its
+answer. The resolver does not apply `GeoAttributionSchema` after a custom mapper,
+strip its application fields or replace its returned object.
 
 When a reload succeeds, new lookups move to the new generation immediately.
 The previous reader closes only after its in-flight lookups finish.
@@ -17048,6 +17144,124 @@ charts, no merged cells and no streaming: an application that needs them takes a
 
 # Upgrading stitchkit
 
+## Released migration: 0.119.0
+
+### factory-default-exposure
+
+**Who must act:** code passing arguments to `createContractFactory`, depending on its fixed-string
+policy types or the renamed exposure types, calling HTTP clients of endpoints typed as the broad
+`EndpointDef` / `FactoryScopedEndpoint`, or declaring multipart endpoints with non-HTTP exposure or
+tool options.
+
+Scope and default transports are inferred separately. Replace the constructor configuration:
+
+```ts
+// before
+const { defineContract } = createContractFactory<AppScope>({ toolExposure: 'explicit' })
+// after: preserve the same curated HTTP-only default
+const { defineContract } = createContractFactory<AppScope>().configure({
+  toolExposure: { default: ['HTTP'] },
+})
+```
+
+To deliberately expose ordinary operations through HTTP and CLI, choose `default: ['HTTP', 'CLI']`
+and remove redundant matching endpoint arrays. Explicit arrays replace, rather than extend, the
+default. Raw responses, multipart, raw bodies, response metadata, response streams and HEAD get only
+HTTP from implicit defaults; a CLI-only or empty default leaves them hidden on every transport.
+Explicit contradictions fail at definition; remove non-HTTP transports and tool options from multipart
+endpoints rather than relying on their silent omission from tool catalogs.
+
+`ExplicitToolExposureEndpoints` and `ExplicitScopedDefineContract` are renamed
+`ConfiguredToolExposureEndpoints<Endpoints, Defaults>` and `ConfiguredScopedDefineContract<Scope, Defaults>`:
+they describe materialization from any default tuple, their second generic, and HTTP-only when it is
+omitted.
+An optional or conditional endpoint override remains an alternative in the returned type. It does not
+guarantee an HTTP client method unless every alternative includes HTTP.
+
+HTTP clients and URL builders no longer assume a widened `Transport[]` contains
+HTTP. Pass the literal array directly to `configure` when the HTTP surface is static;
+its const generic infers the tuple. An annotation or `satisfies ContractFactoryConfig`
+on a separately stored configuration does not preserve the tuple by itself.
+Optional capabilities likewise retain the filtered alternative in endpoint types.
+
+The rule reads the endpoint's type, with or without a factory. An endpoint returned by a helper
+annotated `(): EndpointDef` or `(): FactoryScopedEndpoint<Scope>`, or holding a stored
+`readonly Transport[]`, has no HTTP client method or URL, because that type allows an exposure
+without HTTP. Keep the literal type with a const generic helper:
+
+```ts
+// before
+const read = (): FactoryScopedEndpoint<AppScope> => ({ method: 'GET', path: '/', desc: 'Read', output })
+// after
+const endpoint = <const Endpoint extends FactoryScopedEndpoint<AppScope>>(value: Endpoint) => value
+const read = () => endpoint({ method: 'GET', path: '/', desc: 'Read', output })
+```
+
+If every endpoint already has an explicit array, removing the constructor configuration alone also
+preserves exposure. [ADR 0283](../decisions/0283-factory-default-exposure-is-materialized-by-capability.md).
+
+Search patterns: `createContractFactory`, `toolExposure`, `ExplicitToolExposureEndpoints`,
+`ExplicitScopedDefineContract`, `: EndpointDef`, `: FactoryScopedEndpoint`, and multipart endpoints
+with `expose` or `tool`.
+
+### geo-full-snapshot
+
+**Who must act:** code comparing `stitchkit/geo` results by equality, parsing them with a strict
+schema of its own, mutating a returned `GeoAttribution`, or relying on empty labels.
+
+The default mapper returns everything the City + ASN record states: continent, the registered
+country as its own fields, GeoNames identifiers, `accuracyRadiusKm` and `localizedNames` with every
+language. A record that used to give `{ city: 'Bangkok' }` now also gives
+`localizedNames: { city: { en: 'Bangkok' } }`.
+
+```ts
+// before: an application's copy of the shape
+const StoredGeo = z.strictObject({ city: z.string().optional(), countryCode: z.string().optional() })
+// after: the framework's schema, importable from shared code
+import { GeoAttributionSchema } from 'stitchkit/geo/contract'
+```
+
+`GeoAttribution` is readonly to its nested dictionaries; copy before changing a field. Empty labels
+and coordinates outside ±90° / ±180° are omitted. The located country never borrows the registered
+one; write `countryCode ?? registeredCountryCode` where a country for every address is wanted.
+
+Search pattern: `stitchkit/geo`, `mapGeoIpRecord`, `GeoAttribution`, `resolve(`.
+
+### raw-tracking-attribution
+
+**Who must act:** code passing `referrerMap` or `hostname` to `resolveAttribution`, importing
+`ReferrerRule` or `parseReferrer`, relying on inferred, lowercased or retained UTM, or reading `utm`
+from an event batch on the server.
+
+Tracking sends raw attribution facts. Remove `referrerMap`, `ReferrerRule`, `parseReferrer` and the
+resolver's `hostname`; `TrackingPageContext` and `browserTrackingHost()` no longer require or return
+`hostname` either. Classify `referrer` and campaign tags on your server instead. Configure the
+click-marker names your application recognises:
+
+```ts
+// before
+createTrackingClient({ ...config, referrerMap: [{ pattern: /search\.example/, source: 'search', medium: 'organic' }] })
+// after
+createTrackingClient({ ...config, clickIdParams: ['gclid', 'msclkid'] })
+```
+
+Bootstrap and both touches carry `clickId`, the configured parameter's name without its value. Extend
+your bootstrap DTO or stored attribution shape if you previously copied the framework's fields. No
+marker is recognised unless configured. Real UTM retains its case and whitespace, and a tag without
+`utm_source` is no longer discarded. Keep any channel normalisation in the server classifier.
+
+`currentTouch` is the current capture's context; an untagged entry has no campaign even when a prior
+one did. Implement last-non-direct retention on the server if required. First-touch storage uses a
+versioned format and resets unversioned records once, because inferred and real tags in those records
+cannot be distinguished. Without browser storage, current landing facts still reach bootstrap.
+
+An event batch (`TrackEventsRequest`, the `request` schema of `createTrackingSchemas`) carries
+`buildId` and `events` only. A server that read `request.utm` attributes events through their visit:
+store the bootstrap entry's `utm`, `referrer` and `clickId` with the visit and join on `visitId`.
+
+Search pattern: `referrerMap`, `ReferrerRule`, `parseReferrer`, `resolveAttribution`, `currentTouch`,
+`request.utm`, `input.utm`.
+
 ## Released migration: 0.118.0
 
 ### telegram-due-cursor
@@ -22334,11 +22548,11 @@ from the root `stitchkit`.
 | Export | Kind | Summary |
 |--------|------|---------|
 | `defineContract` | function | declare a contract — [guide](../guide/contracts.md#definecontract) |
+| `ConfiguredScopedDefineContract` | _type_ | scoped authoring parameterized by the exact default transport tuple; explicit endpoint exposure replaces it |
+| `ConfiguredToolExposureEndpoints` | _type_ | endpoint map with materialized exposure; a second generic selects defaults (HTTP when omitted), preserving explicit, optional and conditional overrides |
 | `createContractFactory` | function | a `defineContract` whose scope — on the contract **and** on any endpoint override — is required and held to your union, retaining 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']` |
+| `ContractFactoryConfig` | _type_ | configuration passed to `createContractFactory<Scope>().configure({ toolExposure: { default: [...] } })`; the constructor itself takes no arguments |
+| `ContractFactoryToolExposure` | _type_ | `default: readonly Transport[]`; omitted endpoint exposure uses the immutable policy snapshot, intersected with intrinsic HTTP-only capabilities |
 | `FactoryScopedEndpoint` | _type_ | an endpoint authored through the factory — its own `scope` override is held to the same union |
 | `ScopedContractDef` | _type_ | a factory-defined contract whose `meta.scope` is the required concrete literal |
 | `ScopedDefineContract` | _type_ | the `defineContract` `createContractFactory` returns — endpoint `scope` overrides join the union |
@@ -22558,7 +22772,8 @@ Also re-exports the error helpers from `stitchkit/contract`.
 | `KeyedServices` | _type_ | registry result: the mount-ordered `ServiceDef[]` carrying the same services under `.byKey` |
 | `RegistryHandlers` | _type_ | exact backend handler registry inferred from a contract registry |
 | `ExactRegistryHandlers` | _type_ | fail-first handler shape that rejects extra registry and endpoint keys |
-| `staticRoute` | function | a raw route that serves a directory |
+| `staticRoute` | function | a raw route that serves a contained directory through `serveFile` (`Range` / `304` / validators) |
+| `StaticRouteOptions` | _type_ | `{ cacheControl }` — what `staticRoute` adds to every file it serves |
 | `serveFile` | function | serve a file with `Range` / `304` / `HEAD` — [guide](../guide/server.md#serving-files--range-requests) |
 | `parseByteRange` | function | parse a single `Range` header → range / `unsatisfiable` / `null` |
 | `isWithinDir` | function | path containment — `(root, resolvedTarget) => boolean`; call it before `serveFile` on any URL-derived path |
@@ -23889,7 +24104,7 @@ runtime-tool runner, plus deliberate raw MCP adapters over the same mechanics.
 | `AsyncOperationOutputCapability` | _type_ | optional result/artifact schema plus handler |
 | `RuntimeAsyncOperationConfig` | _type_ | runtime-only descriptor configuration |
 | `RuntimeAsyncOperation` | _type_ | inferred generated definitions and schemas |
-| `AsyncOperationContractConfig` | _type_ | canonical contract config where start returns the operation id; optional `expose` names the transports per capability, because this contract is built inside the framework and never passes through a consumer's `toolExposure: 'explicit'` factory |
+| `AsyncOperationContractConfig` | _type_ | canonical contract config where start returns the operation id; optional `expose` names the transports per capability, because this contract is built inside the framework and never passes through a consumer's configured factory |
 | `AsyncOperationContractWithStartOutputConfig` | _type_ | canonical contract config with an application start envelope and typed id extractor |
 | `DefinedAsyncOperationContract` | _type_ | generated contract, capability keys, schemas and parsed adapters |
 | `ContractAsyncOperationConfig` | _type_ | literal contract method binding and handlers |
@@ -24302,7 +24517,7 @@ shapes are `stitchkit/tracking/contract`, the server half is
 | 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`, `hrefPolicy` (`path-only` by default; `full` retains click query/fragment before `decorate`), `scrollMilestones`, `batchSize`, periods and limits |
+| `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`, `clickIdParams` (ordered application-defined marker names; no values retained), `clickAttributes`, `hrefPolicy` (`path-only` by default; `full` retains click query/fragment before `decorate`), `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 |
@@ -24315,8 +24530,8 @@ shapes are `stitchkit/tracking/contract`, the server half is
 | `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 |
+| `resolveAttribution` / `ResolveAttributionInput` / `ResolvedAttribution` / `AttributionStorage` | function / _type_ | persisted first-touch with TTL, raw current-touch on each capture; actual UTM, referrer and optional `clickId` name from `clickIdParams`; `storage: null` collects without persistence; no channel inference |
+| `parseUtmFromSearch` | function | reads only `utm_*`, preserving case and whitespace up to 200 characters per field; any tag is sufficient, no source required |
 | `redactTrackingText` / `redactTrackingValue` | functions | mask passwords, sign-in credentials and signed launch data in text or a value of any shape; the key stays, and navigation and campaign parameters are untouched |
 | `resolveTrackedClick` / `ResolveTrackedClickOptions` / `TrackedClick` / `TrackedClickAttributes` / `ClickTarget` | function / _type_ | `data-track` → click, `data-track-action` → interaction, a link to another origin → outbound; attribute names configurable; `hrefPolicy: 'full'` retains query/fragment (default `path-only` omits them), URL credentials excluded; `leavesPage` says which path to send on |
 
@@ -24332,7 +24547,7 @@ browser code that only sends events does not import it. → ADR 0280
 | `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`) |
+| `TrackEventsRequest` / `TrackEventsResponse` / `TrackEventsResponseSchema` | _type_ / schema | a batch (`buildId`, `events`; attribution travels with the visit bootstrap) 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` |
@@ -24423,7 +24638,15 @@ adapter is used.
 | `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 |
+| `GeoAttribution` / `mapGeoIpRecord` | _type_ / function | strict readonly sparse City + ASN snapshot: continent, located and registered country as separate facts, GeoNames IDs, first region/city/postal, coordinates/timezone, `accuracyRadiusKm`, autonomous system and all source languages in five `localizedNames` groups; each malformed field is omitted on its own; custom resolver mappers remain app-owned — [guide](../guide/geo.md#lookups) |
+
+## `stitchkit/geo/contract`
+
+The place snapshot's schema, browser-safe, for a shared contract. Brings `zod`.
+
+| Export | Kind | Summary |
+|--------|------|---------|
+| `GeoAttributionSchema` / `GeoAttribution` | schema / _type_ | the strict readonly Zod owner of the snapshot `stitchkit/geo` resolves — [guide](../guide/geo.md#lookups) |
 
 ---
 

package/llms.txt

@@ -9,7 +9,7 @@ Build with stitchkit: define a contract once, then `implement` it and serve it (
 Load the slice for each entrypoint your code imports — `import … from 'stitchkit/server'` → `llms/server.txt`; the root `stitchkit` import → `llms/stitchkit.txt`. A slice holds that entrypoint's API reference section and the guide pages whose home it is; every guide lives in exactly one slice, and a slice that needs another's guide names it under "Also read". Each file is at most 50.0 KB; a longer one continues in numbered parts, each naming the next at its top. Moving across versions: load `llms/upgrading.txt` and the range slices it lists between your version and the target. `llms-full.txt` inlines everything; it is far larger than a context window, so do not read it whole.
 
 ## Entrypoint slices
-- **stitchkit**: [llms/stitchkit.txt](llms/stitchkit.txt) 43.7 KB → [llms/stitchkit.2.txt](llms/stitchkit.2.txt) 43.1 KB
+- **stitchkit**: [llms/stitchkit.txt](llms/stitchkit.txt) 43.9 KB → [llms/stitchkit.2.txt](llms/stitchkit.2.txt) 43.1 KB
 - **stitchkit/live**: [llms/live.txt](llms/live.txt) 21.2 KB
 - **stitchkit/react**: [llms/react.txt](llms/react.txt) 8.7 KB
 - **stitchkit/react/keyboard**: [llms/react-keyboard.txt](llms/react-keyboard.txt) 22.7 KB
@@ -22,9 +22,9 @@ Load the slice for each entrypoint your code imports — `import … from 'stitc
 - **stitchkit/cli**: [llms/cli.txt](llms/cli.txt) 36.5 KB → [llms/cli.2.txt](llms/cli.2.txt) 36.4 KB
 - **stitchkit/cli/publish**: [llms/cli-publish.txt](llms/cli-publish.txt) 1.5 KB
 - **stitchkit/remote**: [llms/remote.txt](llms/remote.txt) 1.0 KB
-- **stitchkit/contract**: [llms/contract.txt](llms/contract.txt) 31.9 KB
+- **stitchkit/contract**: [llms/contract.txt](llms/contract.txt) 33.8 KB
 - **stitchkit/primitives**: [llms/primitives.txt](llms/primitives.txt) 13.2 KB
-- **stitchkit/server**: [llms/server.txt](llms/server.txt) 44.2 KB → [llms/server.2.txt](llms/server.2.txt) 20.5 KB → [llms/server.3.txt](llms/server.3.txt) 47.0 KB → [llms/server.4.txt](llms/server.4.txt) 38.6 KB → [llms/server.5.txt](llms/server.5.txt) 22.9 KB
+- **stitchkit/server**: [llms/server.txt](llms/server.txt) 44.2 KB → [llms/server.2.txt](llms/server.2.txt) 20.9 KB → [llms/server.3.txt](llms/server.3.txt) 47.0 KB → [llms/server.4.txt](llms/server.4.txt) 38.6 KB → [llms/server.5.txt](llms/server.5.txt) 23.1 KB
 - **stitchkit/observability**: [llms/observability.txt](llms/observability.txt) 46.9 KB
 - **stitchkit/agent-runtime**: [llms/agent-runtime.txt](llms/agent-runtime.txt) 44.3 KB → [llms/agent-runtime.2.txt](llms/agent-runtime.2.txt) 46.7 KB → [llms/agent-runtime.3.txt](llms/agent-runtime.3.txt) 43.4 KB
 - **stitchkit/agent-runtime/testing**: [llms/agent-runtime-testing.txt](llms/agent-runtime-testing.txt) 2.6 KB
@@ -47,12 +47,13 @@ Load the slice for each entrypoint your code imports — `import … from 'stitc
 - **stitchkit/telegram/grammy**: [llms/telegram-grammy.txt](llms/telegram-grammy.txt) 1.2 KB
 - **stitchkit/telegram/html**: [llms/telegram-html.txt](llms/telegram-html.txt) 2.7 KB
 - **stitchkit/telegram/screens**: [llms/telegram-screens.txt](llms/telegram-screens.txt) 21.2 KB
-- **stitchkit/tracking**: [llms/tracking.txt](llms/tracking.txt) 20.5 KB
+- **stitchkit/tracking**: [llms/tracking.txt](llms/tracking.txt) 22.3 KB
 - **stitchkit/release**: [llms/release.txt](llms/release.txt) 8.9 KB
 - **stitchkit/tracking/contract**: [llms/tracking-contract.txt](llms/tracking-contract.txt) 2.8 KB
 - **stitchkit/tracking/performance**: [llms/tracking-performance.txt](llms/tracking-performance.txt) 1.1 KB
 - **stitchkit/tracking/server**: [llms/tracking-server.txt](llms/tracking-server.txt) 2.7 KB
-- **stitchkit/geo**: [llms/geo.txt](llms/geo.txt) 4.1 KB
+- **stitchkit/geo**: [llms/geo.txt](llms/geo.txt) 7.0 KB
+- **stitchkit/geo/contract**: [llms/geo-contract.txt](llms/geo-contract.txt) 0.8 KB
 - **stitchkit/xlsx**: [llms/xlsx.txt](llms/xlsx.txt) 4.5 KB
 - **stitchkit/voice**: [llms/voice.txt](llms/voice.txt) 5.2 KB
 - **stitchkit/oauth**: [llms/oauth.txt](llms/oauth.txt) 6.7 KB
@@ -69,11 +70,11 @@ Load the slice for each entrypoint your code imports — `import … from 'stitc
 
 ## Upgrading slices
 - **Upgrading — how to move across versions**: [llms/upgrading.txt](llms/upgrading.txt) 12.7 KB
-- **Upgrading 0.105.0 → 0.118.0**: [llms/upgrading-0.105.0-0.118.0.txt](llms/upgrading-0.105.0-0.118.0.txt) 43.0 KB
-- **Upgrading 0.84.0 → 0.104.0**: [llms/upgrading-0.84.0-0.104.0.txt](llms/upgrading-0.84.0-0.104.0.txt) 46.1 KB
-- **Upgrading 0.63.0 → 0.83.0**: [llms/upgrading-0.63.0-0.83.0.txt](llms/upgrading-0.63.0-0.83.0.txt) 44.0 KB
-- **Upgrading 0.44.0 → 0.62.0**: [llms/upgrading-0.44.0-0.62.0.txt](llms/upgrading-0.44.0-0.62.0.txt) 46.5 KB
-- **Upgrading 0.37.0 → 0.44.0**: [llms/upgrading-0.37.0-0.44.0.txt](llms/upgrading-0.37.0-0.44.0.txt) 14.7 KB
+- **Upgrading 0.106.0 → 0.119.0**: [llms/upgrading-0.106.0-0.119.0.txt](llms/upgrading-0.106.0-0.119.0.txt) 28.8 KB
+- **Upgrading 0.96.0 → 0.105.0**: [llms/upgrading-0.96.0-0.105.0.txt](llms/upgrading-0.96.0-0.105.0.txt) 45.8 KB
+- **Upgrading 0.69.0 → 0.95.0**: [llms/upgrading-0.69.0-0.95.0.txt](llms/upgrading-0.69.0-0.95.0.txt) 46.6 KB
+- **Upgrading 0.55.0 → 0.68.0**: [llms/upgrading-0.55.0-0.68.0.txt](llms/upgrading-0.55.0-0.68.0.txt) 47.0 KB
+- **Upgrading 0.37.0 → 0.53.0**: [llms/upgrading-0.37.0-0.53.0.txt](llms/upgrading-0.37.0-0.53.0.txt) 32.6 KB
 
 ## Guide (web)
 - [Getting started](https://github.com/max-listov/stitchkit/blob/master/docs/guide/getting-started.md): install, entrypoints, and a first contract → server → client app