stitchkit 0.59.3 → 0.59.4

package/llms-full.txt

@@ -3766,6 +3766,10 @@ signal APIs when one managed server is already the complete lifecycle boundary.
 The neutral entrypoint is server-only and works on Bun and Node ≥ 22. It does
 not import provider SDKs.
 
+For complete database, poller, queue-consumer and operational-publisher
+cutovers, continue with the executable
+[application migration recipes](./application-migration-recipes.md).
+
 ## Minimal composition
 
 ```ts
@@ -3878,6 +3882,58 @@ through a Fetch-compatible handler, suitable for a raw route on Bun or Node.
 Product-specific probes may be composed beside it; do not put secrets or raw
 provider failures in the response.
 
+For the conventional three-route surface, reuse the same semantics instead of
+copying them into the application:
+
+```ts
+const operational = createApplicationOperationalHandlers(app)
+
+const rawRoutes = [
+  { method: 'GET', path: '/status', handler: operational.status },
+  { method: 'GET', path: '/ready', handler: operational.readiness },
+  { method: 'GET', path: '/live', handler: operational.liveness },
+]
+```
+
+`status` always returns the current sanitized snapshot with HTTP 200, including
+while starting, draining or stopped. The two probes retain the existing
+readiness/liveness status and `Retry-After` policy.
+
+Applications that already own an OpenTelemetry SDK may inject its `Meter` into
+the isolated adapter:
+
+```ts
+import { createApplicationOpenTelemetry } from 'stitchkit/application/opentelemetry'
+
+const telemetry = createApplicationOpenTelemetry({
+  meter,
+  application: app,
+  activities: [activity],
+  schedules: [schedule],
+})
+
+// During application cleanup:
+telemetry.close()
+```
+
+The adapter registers fixed observable gauges and pulls the latest canonical
+snapshots on every collection. It owns no exporter, SDK lifecycle, cache,
+subscription or polling loop. Attributes are limited to declared application,
+resource, activity, stage and schedule IDs plus bounded framework states;
+epoch, revision, timestamps, failures and product/provider identities are never
+metric attributes. Install `@opentelemetry/api` only when this entrypoint is
+used; the neutral `stitchkit/application` graph remains peer-free.
+
+Every instrument uses unit `1` and reports an absolute current/lifetime value:
+
+| Instruments | Meaning |
+|---|---|
+| `stitchkit.application.lifecycle`, `.ready` | current lifecycle/health fact and readiness |
+| `stitchkit.application.admission.accepting`, `.accepted`, `.completed`, `.pending` | current gate and absolute lifetime admission counts |
+| `stitchkit.application.resource.ready` | readiness for each declared resource with required/state/health attributes |
+| `stitchkit.application.schedule.accepting`, `.active`, `.queued`, `.runs_started`, `.runs_completed`, `.runs_failed`, `.ticks_skipped` | current schedule state and absolute run/tick counts |
+| `stitchkit.application.activity.active`, `.queued`, `.completed`, `.failed` | absolute stage projections for declared activity sources |
+
 ## Admission and graceful shutdown
 
 Use the application operation lease for work that is not already counted by a
@@ -4037,6 +4093,154 @@ retry rules do **not** disappear. They were never process-local glue and remain
 application-owned.
 
 
+==============================================================================
+# Guide: Application migration recipes  (docs/guide/application-migration-recipes.md)
+==============================================================================
+
+---
+title: Application migration recipes
+description: Executable patterns for moving database, poller, queue and operational publishing lifecycle into the managed application kernel.
+type: architecture
+status: active
+created: 2026-08-24
+updated: 2026-08-24
+---
+
+# Application migration recipes
+
+These recipes are the migration companion to the
+[managed application kernel](./application-kernel.md). Their canonical source is
+the packed-consumer fixture
+[`application-migration-recipes.ts`](../../packages/core/scripts/consumer-lane/fixtures/minimal/src/application-migration-recipes.ts):
+the consumer lane installs the package tarball, typechecks that file and runs it
+only through `stitchkit/application` exports.
+
+## Database connection
+
+Wrap connection allocation and readiness in `start`, and make `close` safe after
+partial setup. Stitchkit invokes cleanup for every attempted start, including a
+start that allocates a client and then rejects.
+
+```ts
+const database = defineManagedResource({
+  id: 'database',
+  async start({ signal, reportHealth }) {
+    await databaseClient.connect(signal)
+    await databaseClient.assertReady()
+    reportHealth('healthy')
+  },
+  close: () => databaseClient.close(),
+})
+```
+
+The application still owns the client, ORM configuration, transactions,
+migrations and reconnect policy. The executable recipe deliberately fails after
+allocation and proves one rollback close.
+
+## Long-running poller
+
+Return separate readiness and completion promises. Readiness says dependants may
+start; completion represents the whole background lifetime.
+
+```ts
+const poller = defineManagedResource({
+  id: 'poller',
+  start: ({ signal }) => ({
+    ready: providerPoller.ready,
+    completion: providerPoller.run(signal),
+  }),
+  stopAdmission: () => providerPoller.stop(),
+  drain: () => providerPoller.completion,
+  close: () => providerPoller.close(),
+})
+```
+
+Completion before readiness fails startup and rolls back. Completion after
+readiness removes application readiness. Provider cursor persistence, retry,
+backoff and restart policy remain application/provider concerns.
+
+## Queue consumer
+
+Acquire the application lease only after provider delivery/claim. If admission
+is already closed, reject the delivery through the provider's own nack/requeue
+primitive. Work admitted before shutdown releases its lease after ack/nack and
+therefore participates in application drain.
+
+```ts
+async function handleDelivery(delivery: Delivery) {
+  const lease = app.admission.acquire()
+  if (!lease) return delivery.nack({ requeue: true })
+  try {
+    await processClaim(delivery.claim)
+    await delivery.ack()
+  } catch (error) {
+    await delivery.nack({ requeue: shouldRetry(error) })
+    throw error
+  } finally {
+    lease.release()
+  }
+}
+```
+
+Stitchkit owns only process-local admission accounting and drain. Durable claims,
+visibility timeouts, deduplication, idempotency and retry classification remain
+in the queue/product layer.
+
+## Operational publisher
+
+Project anonymous aggregate activity, then feed absolute snapshots into the
+latest-value sink. A slow transport holds one write plus one replaceable latest
+revision rather than an unbounded event queue.
+
+```ts
+const publisher = createApplicationSnapshotSink({
+  write: (snapshot) => monitoring.publish(snapshot),
+})
+const activity = createActivityProjection({
+  id: 'generation',
+  stages: ['queued', 'running'],
+})
+const unsubscribe = activity.subscribe((snapshot) => {
+  publisher.publish(snapshot)
+})
+
+// cleanup boundary
+unsubscribe()
+publisher.publish(activity.getSnapshot())
+await publisher.close()
+```
+
+The monitoring backend, transport retry and cross-process aggregation remain
+outside Stitchkit. The executable recipe blocks revision 0, coalesces
+intermediate revisions, explicitly admits the final absolute snapshot after
+unsubscribe and proves that `close()` flushes revision 3. Do not rely on an
+asynchronous subscriber callback racing cleanup: publish `getSnapshot()` before
+closing the outer sink, so any older or duplicate late delivery is rejected as
+stale instead of dropping the final state.
+
+## Deletion checklist
+
+After the cutover, remove the old generic lifecycle path completely:
+
+- duplicate `process.on(...)` handlers and shutdown promise caches;
+- manual readiness waiters and resource close fan-out;
+- raw interval handles, overlap flags and timer drain code;
+- global in-flight counters and waiter sets replaced by application leases;
+- progress delta queues replaced by absolute snapshot publishing.
+
+Keep the product code that still owns durable state and policy:
+
+- database schema, transactions and migrations;
+- queue claims, ack/nack, deduplication and external-effect idempotency;
+- provider cursor, retry/backoff and credentials;
+- monitoring transport configuration and durable retention;
+- process exit code, hard-exit and deployment/supervisor policy.
+
+Run the old and new lifecycle paths separately during development if needed,
+but do not ship both. Before cutover, verify there is exactly one signal binding,
+one timer owner, one admission gate and one resource cleanup chain.
+
+
 ==============================================================================
 # Guide: CLI  (docs/guide/cli.md)
 ==============================================================================
@@ -6451,6 +6655,63 @@ The suite in `packages/core/tests` is the working reference for testing each
 piece. Its size changes with the public surface, so the guide does not pin a
 count that can drift independently from the test runner.
 
+### Managed-resource conformance
+
+Consumer-owned resource adapters can run the framework's deterministic
+lifecycle matrix without importing `bun:test`:
+
+```ts
+import { defineManagedResource } from 'stitchkit/application'
+import { runManagedResourceConformance } from 'stitchkit/testing'
+
+await runManagedResourceConformance({
+  createFixture: ({ controls }) => {
+    const resource = defineManagedResource({
+      id: 'provider-adapter',
+      async start() {
+        await controls.startup
+        return {
+          ready: controls.readiness,
+          completion: controls.completion,
+        }
+      },
+      activate: () => controls.activation,
+      stopAdmission: () => provider.stopAdmission(),
+      drain: () => provider.drain(),
+      close: () => controls.close,
+      force: () => controls.force,
+    })
+    return {
+      resource,
+      dispose: () => provider.releaseFixtureHandles(),
+    }
+  },
+})
+```
+
+The runner creates a fresh fixture for every scenario and controls startup,
+readiness, long-lived completion, activation, close and force settlement. The
+adapter must wire those promises to the corresponding public resource phases;
+`dispose` releases fixture-owned handles even after a failed scenario. Semantic
+ordering uses controlled barriers and shutdown abort, while
+`watchdogTimeoutMs` is only an emergency bound for a broken fixture. An
+explicit `scenarios` subset must contain at least one stable scenario ID.
+
+### Published-package optional-peer matrix
+
+The repository's `consumer-lane` is a release invariant over the package users
+actually install, not the source tree. One declarative matrix classifies every
+public export and relevant mixed-barrel feature by browser/Bun/Node target,
+installed optional peers, runtime bundle inputs, emitted-declaration inputs and
+whether the built artifact can execute. Exact export-map coverage means a new
+subpath fails the gate until its dependency boundary is explicit.
+
+Peer-neutral cases run from a packed minimal install. Provider adapters run only
+with their declared peer family and retain a negative missing-peer proof. A new
+runtime or type-only package outside a case's budget fails with both the case id
+and package name, so an accidental eager import cannot hide behind another
+fixture's transitive dependency.
+
 ## Deployment
 
 ### Build
@@ -8426,7 +8687,9 @@ Also re-exports the error helpers from `stitchkit/contract`.
 
 Server-only process-local application composition. See the
 [application kernel guide](../guide/application-kernel.md) and
-[architecture](../architecture/application-kernel.md).
+[architecture](../architecture/application-kernel.md). Complete consumer
+cutovers are covered by the executable
+[migration recipes](../guide/application-migration-recipes.md).
 
 ### Kernel and resources
 
@@ -8436,12 +8699,14 @@ Server-only process-local application composition. See the
 | `defineManagedResource` | function | retain the exact typed resource declaration; every invoked start is rollback-eligible |
 | `managedServerResource` | function | adapt an existing managed server without copying its HTTP/WebSocket shutdown machine |
 | `createApplicationHealthHandler` | function | build a Fetch-clean liveness or readiness response from the sanitized application snapshot |
+| `createApplicationOperationalHandlers` | function | compose always-readable status plus the canonical readiness/liveness handlers |
 | `ApplicationAdmissionError` | class | stable `APPLICATION_NOT_ACCEPTING` rejection from `admission.run(...)` |
 | `ApplicationConfig` / `ApplicationHandle` | _type_ | application declaration and its start/snapshot/subscription/admission/shutdown handle |
 | `ApplicationAdmission` / `ApplicationOperationLease` | _type_ | atomic process-local admission and idempotent release primitive |
 | `ManagedResource` / `ManagedResourceContext` / `ManagedResourceStartResult` | _type_ | resource lifecycle callbacks, shared deadlines, health reporting and separate readiness/completion promises |
 | `ManagedServerResourceConfig` | _type_ | existing managed server, stable ID, dependencies and policy for `managedServerResource` |
 | `ApplicationHealthHandlerOptions` / `ApplicationHealthHandlerOptionsSchema` | _type_ / schema | liveness/readiness selection and sanitized `Retry-After` policy |
+| `ApplicationOperationalHandlers` / `ApplicationOperationalHandlersOptions` / `ApplicationOperationalHandlersOptionsSchema` | _type_ / schema | conventional status/readiness/liveness route surface and shared retry policy |
 
 ### Managed schedules
 
@@ -8506,6 +8771,20 @@ does not resolve grammY.
 | `GrammyWebhookResourceConfig` / `GrammyWebhookResource` | _type_ | injected webhook bot declaration and `{ resource, handleUpdate }` handle |
 | `GrammyUpdate` | _type_ | exact update input inferred from the injected grammY bot context |
 
+## `stitchkit/application/opentelemetry`
+
+Type-only optional-peer adapter for applications that already own an
+OpenTelemetry SDK and exporter. Its observable gauges pull absolute canonical
+snapshots; the adapter owns no SDK lifecycle, polling or delta state.
+
+| Export | Kind | Summary |
+|--------|------|---------|
+| `createApplicationOpenTelemetry` | function | register fixed observable application, resource, admission, schedule and activity gauges on an injected Meter |
+| `ApplicationOpenTelemetryConfig` | _type_ | injected meter and canonical application/activity/schedule pull sources plus isolated diagnostic hook |
+| `ApplicationOpenTelemetryBinding` | _type_ | idempotent exact callback removal and closed state |
+| `ApplicationTelemetryMeter` | _type_ | minimal structural `Meter.createObservableGauge` boundary compatible with `@opentelemetry/api` |
+| `ApplicationOpenTelemetryCollectionError` | _type_ | isolated instrument-name/error diagnostic without product/provider attributes |
+
 ---
 
 ## `stitchkit/agent-runtime`
@@ -8947,6 +9226,16 @@ handler pipeline without opening a TCP port.
 | `createHandlerTestClients` | function | exact contract-registry batch form |
 | `runAgentStoreConformance` | function | reusable black-box duplicate/coalescing/stale/recovery contract for durable agent-store adapters |
 | `AgentStoreConformanceConfig` | _type_ | factory configuration for running the same contract against a fresh adapter |
+| `runManagedResourceConformance` | function | run the canonical deterministic lifecycle matrix against a fresh consumer-owned `ManagedResource` fixture; resolves `void` or throws `ManagedResourceConformanceError` with a stable scenario ID and normalized trace |
+| `ManagedResourceConformanceScenarioIdSchema` / `ManagedResourceConformanceScenarioId` | schema / _type_ | stable clean, rollback, readiness/completion, activation, shutdown-race and forced-cleanup scenario vocabulary |
+| `ManagedResourceConformanceScenarioSchema` / `ManagedResourceConformanceScenario` | schema / _type_ | discriminated scenario record including whether the controlled resource is required |
+| `ManagedResourceConformanceTraceEntrySchema` / `ManagedResourceConformanceTraceEntry` | schema / _type_ | sequence-numbered phase/outcome diagnostic without timestamps or generated IDs |
+| `ManagedResourceConformancePhaseSchema` / `ManagedResourceConformancePhase` | schema / _type_ | lifecycle and disposal trace phases |
+| `ManagedResourceConformanceTraceOutcomeSchema` / `ManagedResourceConformanceTraceOutcome` | schema / _type_ | normalized `enter`, `resolve` or `reject` outcome |
+| `ManagedResourceConformanceConfig` | _type_ | fresh-fixture factory, optional scenario subset and emergency watchdog bound |
+| `ManagedResourceConformanceFactoryInput` / `ManagedResourceConformanceControls` | _type_ | current discriminated scenario and caller-controlled startup, readiness, completion, activation, close and force promises |
+| `ManagedResourceConformanceFixture` | _type_ | tested resource plus required bounded disposal callback |
+| `ManagedResourceConformanceError` | class | `MANAGED_RESOURCE_CONFORMANCE_FAILED` diagnostic carrying scenario, expected phase subsequence and observed trace |
 | `createAgentRaceBarrier` / `createAgentRaceDriver` / `createAgentRaceTrace` | function | bounded named barriers and exact partial-order traces for deterministic runtime race probes |
 | `AgentRaceBarrier` / `AgentRaceDriver` / `AgentRaceTrace` / `AgentRaceTraceEntry` | _type_ | public packed-consumer types for the deterministic race harness |
 | `HandlerTestClientDefaults` | _type_ | ordinary bare-client defaults with handler-owned `baseUrl` and `fetch` removed |

package/llms.txt

@@ -12,6 +12,7 @@ Build with stitchkit: define a contract once, then `implement` it and serve it (
 - [MCP & agents](https://github.com/max-listov/stitchkit/blob/master/docs/guide/mcp-and-agents.md): contracts as MCP tools (createMcpHandler) and AI-agent tools (mountAgent); tool lifecycle, extend, identity
 - [Agent application runtime](https://github.com/max-listov/stitchkit/blob/master/docs/guide/agent-runtime.md): optional durable history, prompt/model composition, stream loop, coordination, fencing and events
 - [Managed application kernel](https://github.com/max-listov/stitchkit/blob/master/docs/guide/application-kernel.md): process-local resources, readiness, admission, schedules, projections and optional provider adapters
+- [Application migration recipes](https://github.com/max-listov/stitchkit/blob/master/docs/guide/application-migration-recipes.md): executable database, poller, queue-consumer and operational publishing cutovers
 - [CLI](https://github.com/max-listov/stitchkit/blob/master/docs/guide/cli.md): contracts as a command-line program
 - [Realtime](https://github.com/max-listov/stitchkit/blob/master/docs/guide/realtime.md): Socket.IO server/client wrappers, handshake auth, the cache bridge, a raw WebSocket lane
 - [Auth & errors](https://github.com/max-listov/stitchkit/blob/master/docs/guide/auth-and-errors.md): scopes, createAuthHook, JWT/cookies, the AppError model, the stitch error-code registry

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "stitchkit",
-  "version": "0.59.3",
+  "version": "0.59.4",
   "description": "Contract-first backend framework — one defineContract() into an HTTP API, MCP tools, AI-agent tools and a typed client. Bun and Node.",
   "keywords": [
     "bun",
@@ -92,6 +92,10 @@
       "types": "./dist/application-grammy.d.ts",
       "import": "./dist/application-grammy.js"
     },
+    "./application/opentelemetry": {
+      "types": "./dist/application-opentelemetry.d.ts",
+      "import": "./dist/application-opentelemetry.js"
+    },
     "./testing": {
       "types": "./dist/testing.d.ts",
       "import": "./dist/testing.js"
@@ -111,7 +115,7 @@
   "scripts": {
     "check": "bun x tsc --noEmit",
     "build:browser": "bun build src/index.ts src/react.ts src/contract/index.ts --outdir dist --target node --packages external --splitting --root src",
-    "build:server": "bun build src/server/index.ts src/node.ts src/tools.ts src/cli.ts src/remote.ts src/files.ts src/testing.ts src/observability/index.ts src/agent-runtime.ts src/agent-runtime-openrouter.ts src/application.ts src/application-grammy.ts --outdir dist --target node --packages external --splitting --root src",
+    "build:server": "bun build src/server/index.ts src/node.ts src/tools.ts src/cli.ts src/remote.ts src/files.ts src/testing.ts src/observability/index.ts src/agent-runtime.ts src/agent-runtime-openrouter.ts src/application.ts src/application-grammy.ts src/application-opentelemetry.ts --outdir dist --target node --packages external --splitting --root src",
     "build:js": "bun run build:browser && bun run build:server",
     "build:types": "bun x tsc -p tsconfig.build.json --emitDeclarationOnly",
     "build": "rm -rf dist && bun run build:js && bun run build:types && bun scripts/check-browser-clean.mjs && bun scripts/check-env-live.mjs && bun scripts/check-public-types.mjs",
@@ -126,6 +130,7 @@
   "peerDependencies": {
     "@modelcontextprotocol/ext-apps": "^1.7.2",
     "@modelcontextprotocol/server": "^2.0.0",
+    "@opentelemetry/api": "^1.9.0",
     "@openrouter/ai-sdk-provider": "^3.0.0",
     "@types/bun": "^1.3.14",
     "@socket.io/bun-engine": "^0.1.1",
@@ -150,6 +155,9 @@
     "@modelcontextprotocol/server": {
       "optional": true
     },
+    "@opentelemetry/api": {
+      "optional": true
+    },
     "@openrouter/ai-sdk-provider": {
       "optional": true
     },
@@ -191,6 +199,7 @@
     "@modelcontextprotocol/client": "^2.0.0",
     "@modelcontextprotocol/ext-apps": "^1.7.5",
     "@modelcontextprotocol/server": "^2.0.0",
+    "@opentelemetry/api": "^1.9.0",
     "@openrouter/ai-sdk-provider": "^3.0.0",
     "@socket.io/bun-engine": "^0.1.1",
     "@socket.io/component-emitter": "^3.1.2",

package/dist/{index-0tszzfxp.js → index-s8w2y7kr.js}

@@ -1,6 +1,3 @@
-import {
-  ShutdownOptionsSchema
-} from "./index-dk6e56g0.js";
 import {
   DEFAULT_PROCESS_SIGNALS,
   RUNTIME_CONTEXT_RESERVED_KEYS,
@@ -11,6 +8,9 @@ import {
   guardSignalCallback,
   reportSignalError
 } from "./index-41wm56v0.js";
+import {
+  ShutdownOptionsSchema
+} from "./index-dk6e56g0.js";
 import {
   errorCode,
   extractIp,