stitchkit 0.70.6 → 0.72.0

package/llms-full.txt

@@ -48,6 +48,7 @@ own, recorded as an ADR.
 |--------|--------|----------|-------|
 | `stitchkit` | browser **and** server | stable | `defineContract`, `createClient`, `createHttpClient`, `createSocketIOClient`, `parseSSE`, the error model |
 | `stitchkit/contract` | browser **and** server | stable | the contract layer alone — `defineContract`, errors, pagination |
+| `stitchkit/primitives` | browser **and** server | evolving | generic values and declarations for lifecycle, access, audit, delivery and exports |
 | `stitchkit/server` | server (Bun) | stable | `createServer`, `implement`, hooks, auth, Socket.IO server, server primitives |
 | `stitchkit/node` | server (Node ≥ 22) | stable | `serveNode` + the runtime-agnostic core — the Node mirror of `/server` |
 | `stitchkit/tools` | server | stable | `createMcpHandler`, `mountMcp`, `mountAgent`, the OAuth provider, native tools |
@@ -55,11 +56,12 @@ own, recorded as an ADR.
 | `stitchkit/cli` | server | stable | `createCli` — the CLI transport, light (no MCP SDK / `ai`) |
 | `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/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` | build and deployment tooling (Bun or Node) | evolving | `ProjectDeclarationSchema` — the one machine-readable statement a repository makes about itself |
 | `stitchkit/react` | browser | stable | `createCursorQuery`, `createCacheBridge` |
-| `stitchkit/agent-runtime` | server | evolving<br>_redefined in 10 of the 15 minors since 0.56.2, most recently 0.69.0_ | optional durable conversation/run loop, history, models, prompts, fencing and events |
+| `stitchkit/agent-runtime` | server | evolving<br>_redefined in 10 of the 17 minors since 0.56.2, most recently 0.69.0_ | optional durable conversation/run loop, history, models, prompts, fencing and events |
 | `stitchkit/agent-runtime/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 |
@@ -67,7 +69,7 @@ own, recorded as an ADR.
 | `stitchkit/agent-runtime/sqlite/bun` | server (Bun) | evolving | durable built-in SQLite store for the agent runtime |
 | `stitchkit/agent-runtime/sqlite/node` | server (Node ≥ 22.5) | evolving | durable built-in SQLite store for the agent runtime |
 | `stitchkit-tui` | terminal (Bun) | evolving | optional official OpenTUI host over a caller-composed headless runtime |
-| `stitchkit/application` | server | evolving<br>_redefined in 3 of the 15 minors since 0.56.2, most recently 0.67.0_ | managed resource graph, readiness, admission, schedules and bounded shutdown |
+| `stitchkit/application` | server | evolving<br>_redefined in 4 of the 17 minors since 0.56.2, most recently 0.72.0_ | managed resource graph, readiness, admission, schedules and bounded shutdown |
 | `stitchkit/application/grammy` | server | evolving | isolated grammY polling and webhook lifecycle adapters |
 | `stitchkit/application/opentelemetry` | server | evolving | maps application snapshots onto an injected OpenTelemetry `Meter` |
 
@@ -180,6 +182,7 @@ map — feature → packages:
 | **Socket.IO server on Node** | `socket.io` |
 | Socket.IO client | `socket.io-client` (runtime peer; unrelated root declarations remain peer-free) |
 | grammY lifecycle adapters (`stitchkit/application/grammy`) | `grammy` |
+| Telegram platform primitives (`stitchkit/telegram`) | — (peer-free) |
 | OpenTelemetry gauges (`stitchkit/application/opentelemetry`) | `@opentelemetry/api` |
 
 ```bash
@@ -2563,6 +2566,49 @@ Set `finalLine: 'require-newline'` when the final newline is part of the
 protocol's truncation proof. The default `allow` continues to accept one valid
 final JSON document without a newline.
 
+## Resumable streams
+
+A stream that survives a dropped connection needs four things beyond opening it:
+re-open, back off before retrying, resume from where it stopped rather than
+restart, and stop for good on a terminal item. `resumableIterator` owns those
+four; your code keeps every decision that is about your data.
+
+```ts
+import { resumableIterator } from 'stitchkit'
+
+for await (const event of resumableIterator<Event, string>({
+  async open(cursor) {
+    const url = cursor ? `/api/events?after=${cursor}` : '/api/events'
+    return parseNDJSON(await fetch(url, { signal }))
+  },
+  advance: (event) => event.id,          // what "where it stopped" means
+  isTerminal: (event) => event.done,     // which item ends the stream
+  retry: { minDelayMs: 500, maxDelayMs: 30_000, jitter: 0.5 },
+  signal,
+  onAttempt: ({ number, delayMs, error }) => log.warn({ number, delayMs, error }),
+})) {
+  render(event)
+}
+```
+
+`open` receives the cursor produced by the last **delivered** item, so a source
+that fails after three items re-opens after the third, not from the beginning.
+A source that simply ends without a terminal item is treated as a dropped
+connection — that is the case a hand-written loop usually mistakes for
+completion, and it is why the stream stops resuming.
+
+**Jitter is not a detail.** Without it every consumer that lost the same server
+retries at the same instant and the fleet arrives together on a server that has
+just come back. The randomisation only ever *shortens* a delay, so `maxDelayMs`
+stays a real ceiling. `createBackoff({ minDelayMs, maxDelayMs, jitter })` is the
+same policy as a standalone value — `next()` and `reset()` — when you need the
+delays without the iterator.
+
+A delivered item resets the backoff, so a stream that reconnects, works for an
+hour and drops again starts its next retry at `minDelayMs` rather than the
+ceiling it reached last time. Aborting the signal ends the iteration promptly,
+including in the middle of a wait.
+
 
 ==============================================================================
 # Guide: MCP & agents  (docs/guide/mcp-and-agents.md)
@@ -4101,7 +4147,8 @@ responses and results with a different call or tool name are invalid; dropping a
 approval input fails the run with a private diagnostic rather than starting a fresh model turn.
 
 `stitchkit/agent-runtime/coding-tools` returns ordinary direct runtime tools named `read_file`,
-`write_file`, `search_files`, `apply_patch`, `run_command` and optional `read_output`. Every call passes a
+`write_file`, `edit_file`, `list_directory`, `glob`, `search_files`, `run_command` and optional
+`read_output`. Every call passes a
 required host authorization callback. File paths are relative, bounded and contained after
 descriptor-relative resolution: each ancestor is opened without following symlinks and remains
 pinned through authorization and the filesystem effect. Reads revalidate the pinned file identity;
@@ -4117,10 +4164,32 @@ Arguments, output and time are bounded, while cancellation terminates the child.
 root and cwd are path boundaries, not a security sandbox: isolate the process when an executable
 must not access the rest of the machine.
 
-`apply_patch` binds the exact source to `baseSha256`, supports dry-run, authorizes the exact
-replacement count, result digest and byte size, then rechecks the base under a per-target lock
-before same-directory atomic replacement. It deliberately does not claim
-multi-file atomicity. With an optional `AgentCodingArtifactStore`, shell output beyond the inline
+`edit_file` replaces one exact snippet. `oldText` is itself the freshness guard for the region it
+changes, so the digest is the optional `expectedSha256` and an edit is one call; pass the digest
+`read_file` returned when you want the whole-file guarantee, and read the `sha256` it returns to
+chain the next edit without re-reading. The read, the occurrence count and the construction of the
+new content all happen inside one per-target lock, so two concurrent edits of different snippets in
+one file cannot each build a file from the same base and have the second erase the first — the lock
+is process-local, which covers many agents in one process and not two processes over one workspace.
+It authorizes the exact replacement count, result digest and byte size, and deliberately does not
+claim multi-file atomicity.
+
+`write_file` creates missing parent directories inside the root and names them in
+`createdDirectories`; the walk that finds them runs before authorization and reports them in the
+authorization payload, so no directory is created before a host approves it.
+
+**Every ordinary outcome is a refusal a model can act on** — a missing file is `NOT_FOUND`, an
+existing file without `overwrite` is `CONFLICT`, an ambiguous snippet is `CONFLICT` carrying its
+occurrence count, a path outside the root is `FORBIDDEN` — each with a `hint` naming the next move.
+Host-level causes stay scrubbed to `INTERNAL_SERVER_ERROR` and name nothing outside the workspace.
+→ ADR 0139
+
+`list_directory` marks excluded directories rather than hiding them, and `glob` reports
+`skippedDirectories` beside its matches: an empty result from a tree whose files all live under an
+excluded directory is not "no files", and a model told only "nothing found" concludes the wrong
+thing. `search_files` takes `regex`, `context` lines and an `include` pattern; regex is bounded by
+refusing backreferences and lookaround and capping line length rather than by a timeout, because a
+JavaScript `RegExp` cannot be interrupted once it starts backtracking. With an optional `AgentCodingArtifactStore`, shell output beyond the inline
 preview continues into an opaque bounded artifact and `read_output` reads slices without
 exposing a host path. Without a store, the previous finite output-limit behavior is unchanged.
 
@@ -4807,6 +4876,40 @@ replace a leading summary on the next compaction.
 Set `maxAttempts` to allow bounded conflict recovery. Every retry reloads the snapshot, reselects the
 eligible range and recomputes the summary; the stale summary is never retried.
 
+### Compacting without the store
+
+The *selection* inside compaction needs no store, no version and no runtime, so
+it is published on its own as `selectCompactableHistory` — for an application
+that drives the model itself and keeps its own history (→ ADR 0142):
+
+```ts
+import { selectCompactableHistory } from 'stitchkit/agent-runtime'
+
+const { leadingSummary, compactable, retained } = selectCompactableHistory({
+  messages,
+  keepRecentTurns: 3,
+})
+if (compactable.length > 0) {
+  const summary = await summarize(compactable, leadingSummary)
+  messages = [summary, ...retained]     // replace the old summary, never stack one
+}
+```
+
+`compactable` is the oldest **whole complete** turns and `retained` is
+everything the model must still hear; together they are the input, in order. A
+turn holding a tool call whose result never arrived is never eligible, and
+neither is anything after it: half a turn hands the provider a call with no
+result, which most of them refuse outright.
+
+`structuredCompaction` calls this same function, so the published selection and
+the runtime's cannot drift into two behaviours. What it adds is the part that
+does need the store — writing the result back under a version check.
+
+Deciding *when* to compact is yours: `AgentRuntimeRunContext.contextUsage`
+carries the last step's prompt size beside the model's window, and dividing them
+is one line where the threshold is decided. The core does not own that ratio, on
+purpose — see ADR 0142 for what it publishes and what it declines to.
+
 ## Observability
 
 `createAgentObservability` emits a separate operator-only `AgentRunEvent`. It
@@ -5550,6 +5653,110 @@ retry rules do **not** disappear. They were never process-local glue and remain
 application-owned.
 
 
+==============================================================================
+# Guide: Generic application primitives  (docs/guide/primitives.md)
+==============================================================================
+
+---
+title: Generic application primitives
+description: Declare lifecycle, access, exact values, audit, delivery and exports without moving application infrastructure into Stitchkit.
+type: guide
+status: active
+created: 2026-09-01
+updated: 2026-09-01
+---
+
+# Generic application primitives
+
+`stitchkit/primitives` is an optional browser-safe leaf. It declares values and policies; it does
+not own a database, transaction, scheduler, durable queue, transport or document generator.
+
+## Lifecycle and access
+
+```ts
+import { defineLifecycle, defineOwnerScope, definePermissionMatrix } from 'stitchkit/primitives';
+import { z } from 'zod';
+
+const lifecycle = defineLifecycle({
+  name: 'document',
+  states: ['draft', 'published'],
+  roles: ['author'],
+  transitions: {
+    publish: {
+      from: 'draft',
+      to: 'published',
+      by: ['author'],
+      payload: z.object({ note: z.string() }),
+    },
+  },
+});
+
+const permissions = definePermissionMatrix({
+  roles: ['reader', 'author'],
+  operations: ['read', 'publish'],
+  grants: {
+    reader: { read: true, publish: false },
+    author: { read: true, publish: true },
+  },
+});
+```
+
+Persist `transition(...).event` in the same application transaction as the next state. A state is
+an immutable branded value; `transition()` produces the next one. `availableTransitions()` and
+`transition()` read the same declaration.
+
+`defineOwnerScope` resolves one owner from authenticated identity. Reading across owners is a
+separate `acrossAllOwners(identity)` call and permission. Pass the resulting branded `OwnerScope`
+to the data adapter. This proves the scope was explicit; Stitchkit cannot prove what SQL an
+arbitrary adapter emits. `scanOwnerFilterRisks` maps existing caller-named manual filters before a
+migration.
+
+## Exact values and deadlines
+
+`defineMoney(currency)` stores integer minor units as a JSON string. Arithmetic keeps the currency
+literal in the type; division and rational shares return an explicit remainder. It does not own
+exchange rates.
+
+`defineUnitSystem` stores exact canonical decimal strings. Every conversion is an application
+rational with an id. A converted `QuantityProjection` is `derived` and carries both its source and
+conversion id; a form/database value can be marked `recorded`. Whether a derived projection is
+persisted or recomputed is an application decision.
+
+`defineDeadlinePolicy` requires an explicit `now`, IANA timezone and elapsed/calendar-day boundary.
+It returns the due instant, signed remaining days, overdue days and caller-owned category key.
+`queryBoundary(now)` returns instants suitable for a data-adapter predicate; reminders and
+escalations are not included.
+
+## Audit and delivery
+
+Put an audit decision beside each operation:
+
+```ts
+meta: { audit: audit.record(z.object({ changed: z.array(z.string()) })) }
+// or
+meta: { audit: audit.omit('read-only projection') }
+```
+
+`assertAuditDeclared(contract)` refuses silence. `createAuditRecord()` validates the change and
+returns a `DomainEvent`; the same id/value can feed both the journal and delivery.
+
+`defineDomainEventDelivery().plan(event)` is pure. Save that event and its destinations in the
+application's transaction. After commit, call `dispatch(event.id)`: the dispatcher accepts only an
+id and obtains actual work from `DomainEventOutbox.claim`. A transport returns `delivered`,
+`retryable`, `terminal` or `unknown`; the dispatcher calls the matching outbox transition. Only
+`retry` may schedule another claim, while `unknown` is held for inspection instead of guessed into
+a retry. The application owns retention and scheduling. There is deliberately no scheduler or
+distributed lease.
+
+## Exports
+
+`defineExportOperation` supplies one input and one result schema to an ordinary contract endpoint.
+A small result can be `ready` with a `ManagedFileRef`; a larger result can be `pending` with the id
+of the application's existing async operation. The input, scope, metadata and tool identity do not
+change. The application creates bytes and owns operation persistence; the managed-file boundary
+streams them.
+
+
 ==============================================================================
 # Guide: Application migration recipes  (docs/guide/application-migration-recipes.md)
 ==============================================================================
@@ -7445,6 +7652,68 @@ const payload = await verifyJwt(token, env.JWT_SECRET)
 `extractToken(req, cookieName?)` reads a bearer token from the `Authorization`
 header, or from the named cookie.
 
+## Telegram Mini Apps
+
+A Mini App hands its backend an `initData` query string that Telegram signed
+with a key derived from the bot token. `verifyTelegramInitData` checks that
+signature and reports what the string says — and refuses with a **reason**,
+because an application answers a stale string differently from a forged one.
+
+```ts
+import { verifyTelegramInitData } from 'stitchkit/telegram'
+import { unauthorized } from 'stitchkit/contract'
+import { env } from './env'
+
+const result = await verifyTelegramInitData({
+  initData,
+  botToken: env.BOT_TOKEN,
+  maxAgeSeconds: 3600,          // a signed string is otherwise valid forever
+})
+if (!result.valid) {
+  // 'missing-hash' | 'signature-mismatch' | 'malformed' | 'expired'
+  throw unauthorized(result.reason === 'expired' ? 'Reopen the app' : 'Invalid session')
+}
+const telegramId = result.data.user?.id
+```
+
+Three things it does that a hand-written check usually does not:
+
+- the **signature is checked first**, before `auth_date` or anything else is
+  read — an expiry inside an unverified payload is a number the sender chose;
+- digests are compared **without an early exit**, so the time a rejection takes
+  is not a measurement of how much of the digest was right;
+- `raw` keeps every signed pair, so a field Telegram adds after this release
+  does not need a release to reach.
+
+`maxAgeSeconds` is optional and there is no default: only the application knows
+how long its own session is worth. Omitting it means the string never expires,
+which is a decision rather than an oversight.
+
+The module is server-only and pulls in no bot library — the token never belongs
+in a browser bundle. `stitchkit/application/grammy` remains the lifecycle
+adapter for an injected grammY bot. Its companion,
+`classifyTelegramSendFailure`, names why a send was refused and separates *retry
+this send* from *stop addressing this recipient*:
+
+```ts
+import { classifyTelegramSendFailure } from 'stitchkit/telegram'
+
+try {
+  await bot.api.sendMessage(chatId, text)
+} catch (error) {
+  const failure = classifyTelegramSendFailure(error)
+  if (failure.recipientUnreachable) await markUnreachable(chatId, failure.reason)
+  else if (failure.retryable) await requeue(chatId, failure.retryAfterSeconds)
+}
+```
+
+The two flags are separate because one answer cannot serve both. A rate limit is
+retryable and implicates nobody; a blocked user is unreachable and no retry
+helps; a message Telegram could not parse is *neither* — the recipient is fine
+and our payload is wrong, which is the case a list of substrings quietly counts
+against the user. An unrecognised refusal leaves the recipient reachable: losing
+a working subscriber forever costs more than one wasted send.
+
 ## Cookies
 
 ```ts
@@ -9172,6 +9441,133 @@ additive** — adopting it changes nothing in your code. (See
 So upgrading is: read the `### ⚠️ Breaking changes` of every version *above* your
 current one *up to* your target, and apply each snippet.
 
+## Released migration: 0.72.0
+
+Nothing you *pass* changed. Both items are about types you read or build, and
+both stop the compiler rather than surprising you at runtime.
+
+### If you read `perKey` off `BoundedAdmissionPolicy`
+
+`perKey` is now a union: the flat ceiling it always was, or `{ maxKeys, limits }`
+where the ceiling is resolved from the key. Declaring one is unchanged; reading
+one needs a narrowing.
+
+```ts
+// before
+const ceiling = policy.perKey?.maxConcurrent
+
+// after
+const ceiling =
+  policy.perKey && !('limits' in policy.perKey) ? policy.perKey.maxConcurrent : undefined
+```
+
+A shape carrying members of both branches — `{ maxKeys, maxConcurrent, limits }` —
+is refused at construction. It does *not* fail to typecheck: an excess-property
+check against a union admits any property some member declares, so this one is
+caught by `createBoundedAdmission`, not by `tsc`.
+
+### If you build a snapshot or a status by hand
+
+`CreditWindowSnapshot` gained `waiting` (producers parked in the new waiting
+`acquire`) and `DiagnosticJournalStatus` gained `lock`. Both are produced by the
+framework, so reading them is unaffected — but a test double stops compiling:
+
+```ts
+// before
+const snapshot: CreditWindowSnapshot = { state: 'open', capacityBytes: 100, /* … */ }
+
+// after
+const snapshot: CreditWindowSnapshot = { state: 'open', capacityBytes: 100, /* … */ waiting: 0 }
+```
+
+## Released migration: 0.71.0
+
+The Agent coding tools. Two of the three changes are visible to the compiler;
+the third is the one to read carefully, because nothing will point at it.
+
+### If you implement `authorize`
+
+The operation union gained `edit`, `list` and `glob` and lost `patch`. An
+exhaustive matcher stops compiling and the compiler shows you every arm. **A
+matcher with a default branch does not**, and that is the dangerous case:
+
+```ts
+// before — and after this upgrade, silently wrong in both directions
+if (request.operation === 'patch') return reviewPatch(request)
+return true            // now also authorizes edit, list and glob
+// …or: return false   // now also kills edit_file
+```
+
+```ts
+// after
+switch (request.operation) {
+  case 'edit':   return reviewEdit(request)   // the old `patch` payload, unchanged
+  case 'list':
+  case 'glob':   return true                  // or your own policy
+  // …existing read / write / search / shell / artifact-read arms
+}
+```
+
+`write` gained `createsDirectories` — the workspace-relative directories the
+call would create, outermost first, reported **before** anything is created. A
+host that wants to refuse implicit directory creation now can.
+
+### If you call `apply_patch`
+
+It is `edit_file`, and it is one call:
+
+```ts
+// before
+const read = await readFile({ path })
+await applyPatch({ path, baseSha256: read.sha256, oldText, newText, dryRun: true })
+await applyPatch({ path, baseSha256: read.sha256, oldText, newText, dryRun: false })
+
+// after
+await editFile({ path, oldText, newText })
+```
+
+`expectedSha256` is optional and still refuses a stale base with `CONFLICT` when
+you pass it; `edit_file` returns the resulting `sha256`, so a chain of edits
+never needs to re-read. If you key an approval policy or a UI label on the string
+`apply_patch`, update the key — nothing will fail loudly.
+
+### If you match on `INTERNAL_SERVER_ERROR` from a coding tool
+
+Ordinary outcomes no longer arrive that way. A missing file is `NOT_FOUND`, an
+existing file without `overwrite` is `CONFLICT`, an ambiguous snippet is
+`CONFLICT` with the occurrence count, a path outside the root is `FORBIDDEN`.
+Code that treated any coding-tool failure as an internal fault will now see
+codes it did not before; code that showed the model an empty error now has a
+sentence and a `hint` to show it. Host-level causes are unchanged and still
+scrubbed.
+
+### If you write files into new directories
+
+Nothing to change: `write_file` creates missing parents inside the root. Read
+`createdDirectories` in the result if you want to notice a typo — a path that
+was a failure before is now a successful write into a new tree.
+
+### If you want a step to know its context budget
+
+Opt in by reading it; nothing is injected for you:
+
+```ts
+loop: {
+  prepareStep: ({ contextUsage }) => {
+    const used = contextUsage?.usedTokens
+    if (used?.provenance === 'unavailable') return {}      // no step has landed yet
+    const fraction = (used?.value ?? 0) / (contextUsage?.contextWindow ?? 1)
+    // …render it wherever you put it
+    return {}
+  },
+}
+```
+
+Put it at the **tail** of the conversation rather than in the system
+instructions unless you have a reason: changing the system prompt on every step
+invalidates the provider's prefix cache for the whole conversation, and on a long
+run that is a multiple of the input cost.
+
 ## Released migration: 0.70.0
 
 ### Descriptor-backed Agent filesystem containment
@@ -11811,6 +12207,8 @@ The browser-and-server entrypoint. Re-exports everything from
 | `createRetainedTopics` | function | retained last-value store for sticky events — [guide](../guide/realtime.md#sticky-events) |
 | `parseSSE` | function | parse an SSE `Response` into an async generator — [guide](../guide/client.md#sse) |
 | `parseNDJSON` | function | parse bounded fatal-UTF-8 NDJSON; blank keep-alives are skipped and `finalLine: 'require-newline'` can make the delimiter mandatory — [guide](../guide/client.md#ndjson) |
+| `resumableIterator` | function | re-open a long-lived stream from the last delivered cursor, with jittered backoff, a caller-owned terminal item and prompt abort — [guide](../guide/client.md#resumable-streams) |
+| `createBackoff` | function | exponential backoff with subtractive jitter as a value: `next()` / `reset()` |
 | `ContractStreamFrameSchema` / `ContractStreamFrame` | schema / _type_ | default on-the-wire `data` / safe `error` / `end` envelope of a contract-first stream |
 | `ContractStreamFraming` / `ContractStreamCompletion` | _types_ | opt-in item-vs-envelope framing and terminal-vs-stream-end completion policies |
 | `StreamFinalLinePolicy` | _type_ | permissive or newline-required final NDJSON line policy |
@@ -11854,6 +12252,10 @@ The browser-and-server entrypoint. Re-exports everything from
 | `RetainedTopics` | _type_ | the `createRetainedTopics` handle |
 | `ParseSSEOptions` | _type_ | options for `parseSSE` |
 | `ParseNDJSONOptions` | _type_ | options for `parseNDJSON` |
+| `BackoffPolicySchema` / `BackoffPolicy` | schema / _type_ | `minDelayMs`, `maxDelayMs` and a `0`–`1` jitter fraction; a ceiling below the floor is refused |
+| `Backoff` | _type_ | the backoff handle returned by `createBackoff` |
+| `ResumableIteratorConfig` | _type_ | caller-owned `open` / `advance` / `isTerminal`, retry policy, abort signal and `onAttempt` observer |
+| `ResumableAttempt` | _type_ | attempt number, the delay about to be waited and the error that caused it |
 
 ### Trace (client)
 
@@ -11965,6 +12367,51 @@ from the root `stitchkit`.
 
 ---
 
+## `stitchkit/primitives`
+
+Browser-and-server-safe declarations for facts an application wants to define once. See the
+[primitives guide](../guide/primitives.md). Storage, transactions, data-adapter predicates,
+schedules, transports and file generation remain application-owned.
+
+| Export | Kind | Summary |
+|--------|------|---------|
+| `defineLifecycle` | function | immutable finite-state transition declaration, role/payload validation, available-action projection and transition event |
+| `LifecycleState` / `LifecycleTransitionDefinition` / `LifecycleDefinition` | _types_ | branded state value and the declaration inferred from application strings |
+| `LifecycleTransitionInput` / `LifecycleTransitionResult` / `LifecycleTransitionSuccess` / `LifecycleTransitionFailure` | _types_ | typed execution input and distinct transition/state, role and payload outcomes |
+| `LifecycleTransitionEventSchema` / `LifecycleTransitionEvent` | schema / _type_ | canonical event returned for application-atomic persistence |
+| `defineOwnerScope` | function | resolve one owner from identity or require the explicit `acrossAllOwners` capability |
+| `OwnerScope` / `OwnerScopeDefinition` / `OwnerScopeResolution` | _types_ | branded adapter input and its resolved/refused outcomes |
+| `definePermissionMatrix` | function | exhaustive role × operation decisions with server check and client capability projection |
+| `PermissionGrantMatrix` / `PermissionCheckResult` | _types_ | compile-time complete matrix and unknown/allowed/denied runtime result |
+| `defineMoney` / `createMoneySchema` | functions | fixed-currency JSON-safe minor-unit value and Zod schema |
+| `addMoney` / `subtractMoney` / `multiplyMoney` / `shareMoney` / `splitMoney` | functions | exact same-currency arithmetic with explicit indivisible remainder |
+| `Money` / `MoneyShare` / `MoneySplit` | _types_ | currency-literal value and remainder-bearing operation results |
+| `defineUnitSystem` / `createQuantitySchema` / `addQuantity` | functions | exact decimal quantities and caller-declared finite conversions |
+| `Quantity` / `UnitConversion` / `QuantityProjection` | _types_ | unit-literal value, rational conversion and recorded/derived provenance |
+| `QuantityProjectionSchema` | schema | transport-safe recorded/derived quantity union |
+| `defineDeadlinePolicy` | function | elapsed- or calendar-day projection with explicit timezone, threshold, current time and caller category keys |
+| `DeadlineResultSchema` / `DeadlineResult` | schema / _type_ | due instant, remaining/overdue days and projected category |
+| `audit` | constant | constructors for explicit `record(changeSchema)` or `omit(reason)` endpoint metadata |
+| `assertAuditDeclared` | function | refuse a contract operation with no audit decision |
+| `createAuditRecord` | function | validate one declared change and return the canonical event value |
+| `AuditPolicy` / `AuditRecordPolicy` / `AuditOmitPolicy` / `CreateAuditRecordInput` | _types_ | audit declaration and record input contracts |
+| `AuditRecordSchema` / `AuditRecord` | schema / _type_ | domain-event-shaped audit record |
+| `createDomainEventSchema` | function | wrap a typed payload in the canonical event envelope |
+| `DomainEventSchema` / `DomainEvent` | schema / _type_ | generic event with stable id, time, subject and optional actor |
+| `DomainEventActorSchema` / `DomainEventActor` | schema / _type_ | structured actor identity and application role |
+| `DomainEventSubjectSchema` / `DomainEventSubject` | schema / _type_ | generic subject type/id pair |
+| `defineDomainEventDelivery` | function | plan routes and dispatch only application-outbox claims by committed event id |
+| `DomainEventDestinationSchema` / `DomainEventDestination` | schema / _type_ | transport-neutral destination identity |
+| `DomainEventDeliveryOutcomeSchema` / `DomainEventDeliveryOutcome` | schema / _type_ | delivered, retryable, terminal or unknown transport result |
+| `DomainEventDeliveryClaimSchema` / `DomainEventDeliveryClaim` | schema / _type_ | application-owned atomic outbox claim |
+| `DomainEventOutbox` / `DomainEventRoute` / `DomainEventTransport` | _types_ | host capabilities composed by process-local delivery |
+| `DomainEventDeliveryPlan` / `DomainEventDispatchResult` | _types_ | transaction input and bounded dispatch summary |
+| `defineExportOperation` / `createExportResultSchema` | functions | one typed contract operation returning a ready managed file or pending operation id |
+| `scanMoneyNumberRisks` / `scanOwnerFilterRisks` | functions | source-text migration diagnostics with caller-owned identifiers |
+| `SourceText` / `SourceRisk` | _types_ | migration scanner input and exact path/line evidence |
+
+---
+
 ## `stitchkit/server`
 
 Server-only. Builds and runs the HTTP server, and carries the server primitives.
@@ -12143,6 +12590,7 @@ Also re-exports the error helpers from `stitchkit/contract`.
 | `generateTraceId` | function | a fresh trace id |
 | `resolveTraceId` | function | the default per-request trace-id resolver |
 | `extractIp` | function | the caller IP from a request |
+| `isPublicIp` | function | whether an address belongs to the public internet; anything unparseable is not |
 | `resolveSocketIp` | function | the caller IP for a Socket.IO handshake (proxy-aware) |
 | `getClientInfo` | function | caller IP + user-agent |
 | `EventBus` | _type_ | the `createEventBus` handle |
@@ -12213,7 +12661,9 @@ cutovers are covered by the executable
 | Export | Kind | Summary |
 |--------|------|---------|
 | `createBoundedAdmission` | function | process-local no-queue global/per-key concurrency and rate leases, optionally composed with application admission |
-| `BoundedAdmissionPolicySchema` / `BoundedAdmissionPolicy` | schema / _type_ | finite global budget and optional finite per-key budget with `maxKeys` |
+| `BoundedAdmissionPolicySchema` / `BoundedAdmissionPolicy` | schema / _type_ | finite global budget and optional finite per-key budget with `maxKeys`, declared either as one flat ceiling or as a resolver — never both |
+| `BoundedAdmissionPerKeyLimitsSchema` / `BoundedAdmissionPerKeyLimits` | schema / _type_ | one key's resolved ceiling: `maxConcurrent` and optional `rate` |
+| `BoundedAdmissionPerKeyLimitResolver` | _type_ | `(key) => limits`, resolved on a key's first admission and cached until the key is evicted |
 | `BoundedRateBudgetSchema` / `BoundedRateBudget` | schema / _type_ | `{ limit, intervalMs }` monotonic sliding-window budget |
 | `BoundedAdmissionStateSchema` / `BoundedAdmissionState` | schema / _type_ | `accepting \| draining \| closed` |
 | `BoundedAdmissionRefusalReasonSchema` / `BoundedAdmissionRefusalReason` | schema / _type_ | exact local/upstream refusal vocabulary |
@@ -12240,6 +12690,8 @@ cutovers are covered by the executable
 | `createCreditWindow` | function | finite byte-credit lease window with exact once-only replenishment |
 | `CreditWindow` / `CreditWindowSnapshot` / `CreditWindowSnapshotSchema` | _type_ / schema | byte-credit handle and absolute accounting record |
 | `CreditAcquireResult` / `CreditLease` | _type_ | reasoned refusal or idempotently releasable byte-credit lease |
+| `CreditAcquireWaitOptions` | _type_ | `signal` / `timeoutMs` for the waiting `acquire` overload; absent budget waits until credit, close or abort |
+| `CreditWaitResult` / `CreditWaitRefusalReason` | _type_ | waiting-acquire outcome; `insufficient-credit` is absent by construction, `timed-out` and `aborted` replace it |
 
 ### Bounded diagnostic journal
 
@@ -12248,6 +12700,7 @@ cutovers are covered by the executable
 | `createDiagnosticJournal` | function | create one schema-owned FIFO JSONL writer with bounded retained memory, exclusive local path ownership and finite rotation |
 | `DiagnosticJournalConfig` / `DiagnosticJournal` | _type_ | owner schema/path/limits/failure observer and the synchronous `submit`, bounded-wait `flush`/`close`, status handle |
 | `DiagnosticJournalLimitsSchema` / `DiagnosticJournalLimits` | schema / _type_ | positive event, pending-item, pending-byte, file-byte and retained-file limits |
+| `DiagnosticJournalLockPolicySchema` / `DiagnosticJournalLockPolicy` | schema / _type_ | `refuse` (default) or `reclaim-stale`, which reclaims only a lock whose recorded owner is provably gone |
 | `DiagnosticJournalSubmitResultSchema` / `DiagnosticJournalSubmitResult` | schema / _type_ | accepted epoch/sequence or explicit invalid, oversized, capacity, closed or failed refusal |
 | `DiagnosticJournalStatusSchema` / `DiagnosticJournalStatus` | schema / _type_ | state, limits, exact admission/write/failure counters, pending ownership, rotations, partial tails and last safe sequences |
 | `DiagnosticJournalFrameSchema` / `DiagnosticJournalFrame` | schema / _type_ | version-1 JSONL frame carrying process epoch, contiguous accepted sequence and schema-validated JSON event |
@@ -12397,6 +12850,8 @@ Server-only optional application runtime. See the
 | `AgentConversationMessagePageSchema` / `AgentConversationMessagePage` | schema / _type_ | cursor-paged durable message history |
 | `composeAgentPrompt` | function | ordered prompt contributions and provenance-aware signed context budget; irreducible reservation deficits are `oversized`, not compactable history |
 | `structuredCompaction` | function | summarize a provider-valid snapshot range and replace it through CAS |
+| `selectCompactableHistory` | function | which oldest whole complete turns may be summarised away — the half of compaction that needs no store (→ ADR 0142) |
+| `SelectCompactableHistoryOptions` / `CompactableHistory` | _type_ | message list, retained-turn count and evidence policy in; `leadingSummary`, `compactable` and `retained` out |
 | `createAgentSessionCoordinator` | function | strict process-local queue/interrupt/supersede lifecycle |
 | `AgentRuntimeStopPolicy` | _type_ | named custom AI SDK stop condition persisted and published on policy stop |
 | `AgentRuntimePrepareStep` | _type_ | per-run controlled step callback with typed domain context and managed run signal/fence |
@@ -12425,6 +12880,29 @@ transport adapters validate the same records. Runtime composition types are `Age
 `AgentSessionCoordinator`, `AgentCompactionContext`, `AgentCompactionResult` and
 `StructuredCompactionConfig`.
 
+A provider refusal is classified rather than phrased. `classifyProviderFailure` returns an
+`AgentProviderFailure` — an `AgentProviderFailureReason` (`insufficient-credits`, `rate-limited`,
+`model-unavailable`, `context-overflow`, `timeout`, `cancelled`, `unknown`), the provider's `status`
+when it supplied one, whether the same request is `retryable` unchanged, and the `evidence` the
+answer rests on: `status` is the provider stating its own answer, `message` is us reading its prose,
+and `none` is an honest refusal to guess. The sentence a user reads stays with the application —
+its tone and its decision about what to admit are not the core's to make. `isToolResultFailure`
+recognises a failure carried inside a *successful* tool result, in both the bare and the
+`{ value: … }` envelope. Both are plain functions and need no runtime. → ADR 0141
+
+`normalizeOpenRouterUsage` is the same normalisation `openRouterProvider`
+applies, exported so an application calling the SDK directly gets provenance-correct numbers
+without adopting the runtime.
+
+`AgentContextUsage` reaches every step through `AgentRuntimeRunContext.contextUsage`: how full the
+model's context is, as `usedTokens` (an `AgentUsageValue`, so it carries the provenance that says
+where the number came from) beside the model's declared `contextWindow`. It is the **last completed
+step's prompt size**, not the run's cumulative input tokens — cumulative counts every step's prompt
+again and is a multiple of the real fill. Before the first step lands there is no provider-reported
+number and the provenance is `unavailable`, which is a different fact from zero. No fraction is
+exposed: dividing is one line where it is rendered, and the output reserve belongs to the
+consumer's prompt budget rather than to this layer.
+
 Canonical protocol exports are `AgentProtocol`, `AgentProtocolConfig`, `AgentTerminalAcceptance`,
 `AgentTerminalAcceptanceInput`, `hasAgentTerminalOutput`, `AgentRecordIdSchema`, `AgentRecordVersionSchema`,
 `AgentTimestampSchema`, `AgentJsonObjectSchema`, `AgentProviderEnvelopeSchema`,
@@ -12566,12 +13044,14 @@ explicit policy; use the Bun or Node SQLite leaf for durable reopen.
 ## `stitchkit/agent-runtime/coding-tools`
 
 Server-only evolving, peer-free direct runtime tools. `createAgentCodingTools(config)` returns
-`read_file`, `write_file`, `search_files`, `apply_patch`, optional `run_command` and, when an
+`read_file`, `write_file`, `edit_file`, `list_directory`, `glob`, `search_files`, optional
+`run_command` and, when an
 artifact store is supplied, `read_output`.
 
 | Export | Kind | Summary |
 |--------|------|---------|
-| `createAgentCodingTools` | function | construct direct host-authorized bounded file, search, guarded patch, shell and artifact runtime-tool definitions; filesystem operations use Linux `/proc/self/fd` or the packaged macOS Node-API backend and otherwise fail closed |
+| `createAgentCodingTools` | function | construct direct host-authorized bounded file, listing, glob, search, exact-snippet edit, shell and artifact runtime-tool definitions; every ordinary refusal is a typed code with an instructive `hint`, and filesystem operations use Linux `/proc/self/fd` or the packaged macOS Node-API backend and otherwise fail closed |
+| `AGENT_CODING_TOOL_NAMES` | const | the mounted tool names — `read_file`, `write_file`, `edit_file`, `list_directory`, `glob`, `search_files`, `run_command`, `read_output` |
 | `AgentCodingToolDefinition` | _type_ | peer-free structural direct-tool shape accepted by the canonical runtime-tool surface |
 | `AgentCodingToolConfig` | _type_ | absolute root, required authorization callback, finite executable alias map, exact child environment and optional limits |
 | `AgentCodingToolAuthorizationSchema` / `AgentCodingToolAuthorization` | schema / _type_ | discriminated read/write/search/patch/shell/artifact decision presented to host policy before effect |
@@ -13094,6 +13574,26 @@ available from `stitchkit/contract`.
 
 ---
 
+## `stitchkit/telegram`
+
+Peer-free server-only Telegram platform primitives. Importing this resolves no
+bot library; `stitchkit/application/grammy` remains the lifecycle adapter for an
+injected grammY bot. → ADR 0143
+
+| Export | Kind | Summary |
+|--------|------|---------|
+| `verifyTelegramInitData` | function | verify a Mini App `initData` signature against the bot token in constant time, before reading anything out of it |
+| `VerifyTelegramInitDataOptions` | _type_ | raw `initData`, bot token, optional `maxAgeSeconds` bound and injected clock |
+| `TelegramInitDataVerification` | _type_ | `{ valid: true, data }` or a refusal carrying its reason |
+| `TelegramInitData` | _type_ | verified `user`/`receiver`, `authDate`, `ageSeconds`, `queryId`, `startParam`, `chatType`, `chatInstance` and every signed pair in `raw` |
+| `TelegramInitDataUser` | _type_ | camelCase user record inferred from Telegram's signed `user` payload |
+| `TelegramInitDataRefusal` | _type_ | `missing-hash` / `signature-mismatch` / `malformed` / `expired` — an expired string is not a forged one |
+| `classifyTelegramSendFailure` | function | name a refused Bot API send and separate "retry this send" from "stop addressing this recipient" |
+| `TelegramSendFailure` | _type_ | reason, `status`, Telegram-stated `retryAfterSeconds`, `retryable`, `recipientUnreachable` and which evidence produced the answer |
+| `TelegramSendFailureReason` | _type_ | `blocked-by-user` / `user-deactivated` / `chat-not-found` / `not-started` / `rate-limited` / `message-invalid` / `server-error` / `unknown` |
+
+---
+
 ## `stitchkit/declaration`
 
 Zod-only, dependency-free. The **project declaration**: the single