stitchkit 0.59.1 → 0.59.2

package/dist/server/process-signals.d.ts

@@ -9,7 +9,7 @@
  * throws, and a third signal on a process whose default disposition the first
  * `process.on` already suppressed. → ADR 0076
  */
-import type { ManagedServerHandle, ShutdownOptions, ShutdownResult } from './shutdown';
+import type { ShutdownOptions, ShutdownResult } from './shutdown';
 /**
  * Signal names this binding can listen for.
  *
@@ -21,8 +21,10 @@ import type { ManagedServerHandle, ShutdownOptions, ShutdownResult } from './shu
  * cannot listen for `SIGTERM` at all.
  */
 export type ProcessSignalName = 'SIGINT' | 'SIGTERM' | 'SIGHUP' | 'SIGQUIT' | 'SIGUSR2' | 'SIGBREAK';
-/** The part of a managed handle this binding uses. */
-export type ShutdownTarget = Pick<ManagedServerHandle<unknown>, 'shutdown'>;
+/** The part of any managed handle this binding uses. */
+export interface ShutdownTarget<TResult = ShutdownResult> {
+    shutdown(options?: ShutdownOptions): Promise<TResult>;
+}
 /** Which phase failed, so one `onError` can tell them apart. */
 export type ProcessSignalsErrorPhase = 'prepare' | 'shutdown' | 'complete';
 /**
@@ -43,7 +45,7 @@ export interface SignalSource {
      */
     raiseDefault(signal: ProcessSignalName): boolean;
 }
-export interface ProcessSignalsOptions {
+export interface ProcessSignalsOptions<TResult = ShutdownResult> {
     /**
      * Defaults to `['SIGINT', 'SIGTERM']`. Duplicates are ignored. Node on Windows
      * cannot listen for `SIGTERM`.
@@ -72,7 +74,7 @@ export interface ProcessSignalsOptions {
      * here. If it throws, `promise` stays resolved — the transport really did shut
      * down — and the failure is reported through `onError('complete', …)`.
      */
-    onComplete?: (result: ShutdownResult) => void | Promise<void>;
+    onComplete?: (result: TResult) => void | Promise<void>;
     /** Reports any phase failure, with the phase that produced it. */
     onError?: (phase: ProcessSignalsErrorPhase, error: unknown) => void;
     /** Runs for every counted signal after the first: one forces, later ones escalate. */
@@ -85,14 +87,14 @@ export interface ProcessSignalsOptions {
      */
     onEscalationBlocked?: (signal: ProcessSignalName) => void;
 }
-export interface ProcessSignalsBinding {
+export interface ProcessSignalsBinding<TResult = ShutdownResult> {
     /**
      * Resolves with the shutdown result, or with `undefined` when the binding was
      * closed before any signal arrived. Rejects only when the shutdown itself
      * failed. Already handled internally, so ignoring it never raises
      * `unhandledRejection`.
      */
-    readonly promise: Promise<ShutdownResult | undefined>;
+    readonly promise: Promise<TResult | undefined>;
     /** Remove the listeners. Idempotent. */
     close(): void;
 }
@@ -113,5 +115,5 @@ export interface ProcessSignalsBinding {
  * is supervisor policy (→ ADR 0074). Set `process.exitCode` in `onComplete` /
  * `onError`.
  */
-export declare function bindProcessSignals(handle: ShutdownTarget, options?: ProcessSignalsOptions): ProcessSignalsBinding;
+export declare function bindProcessSignals<TResult = ShutdownResult>(handle: ShutdownTarget<TResult>, options?: ProcessSignalsOptions<TResult>): ProcessSignalsBinding<TResult>;
 //# sourceMappingURL=process-signals.d.ts.map

package/dist/server/process-signals.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"process-signals.d.ts","sourceRoot":"","sources":["../../src/server/process-signals.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAQH,OAAO,KAAK,EAAE,mBAAmB,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAGvF;;;;;;;;;GASG;AACH,MAAM,MAAM,iBAAiB,GACzB,QAAQ,GACR,SAAS,GACT,QAAQ,GACR,SAAS,GACT,SAAS,GACT,UAAU,CAAC;AAEf,sDAAsD;AACtD,MAAM,MAAM,cAAc,GAAG,IAAI,CAAC,mBAAmB,CAAC,OAAO,CAAC,EAAE,UAAU,CAAC,CAAC;AAE5E,gEAAgE;AAChE,MAAM,MAAM,wBAAwB,GAAG,SAAS,GAAG,UAAU,GAAG,UAAU,CAAC;AAE3E;;;GAGG;AACH,MAAM,WAAW,YAAY;IAC3B,EAAE,CAAC,MAAM,EAAE,iBAAiB,EAAE,OAAO,EAAE,MAAM,IAAI,GAAG,IAAI,CAAC;IACzD,GAAG,CAAC,MAAM,EAAE,iBAAiB,EAAE,OAAO,EAAE,MAAM,IAAI,GAAG,IAAI,CAAC;IAC1D;;;;;;;;OAQG;IACH,YAAY,CAAC,MAAM,EAAE,iBAAiB,GAAG,OAAO,CAAC;CAClD;AAED,MAAM,WAAW,qBAAqB;IACpC;;;OAGG;IACH,OAAO,CAAC,EAAE,SAAS,iBAAiB,EAAE,CAAC;IACvC;;;;OAIG;IACH,QAAQ,CAAC,EAAE,IAAI,CAAC,eAAe,EAAE,QAAQ,CAAC,CAAC;IAC3C,YAAY,CAAC,EAAE,YAAY,CAAC;IAC5B;;;;;;;;;OASG;IACH,UAAU,CAAC,EAAE,CAAC,MAAM,EAAE,iBAAiB,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACjE;;;;OAIG;IACH,UAAU,CAAC,EAAE,CAAC,MAAM,EAAE,cAAc,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC9D,kEAAkE;IAClE,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,wBAAwB,EAAE,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;IACpE,sFAAsF;IACtF,gBAAgB,CAAC,EAAE,CAAC,MAAM,EAAE,iBAAiB,EAAE,KAAK,EAAE,OAAO,GAAG,UAAU,KAAK,IAAI,CAAC;IACpF;;;;;OAKG;IACH,mBAAmB,CAAC,EAAE,CAAC,MAAM,EAAE,iBAAiB,KAAK,IAAI,CAAC;CAC3D;AAED,MAAM,WAAW,qBAAqB;IACpC;;;;;OAKG;IACH,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC,cAAc,GAAG,SAAS,CAAC,CAAC;IACtD,wCAAwC;IACxC,KAAK,IAAI,IAAI,CAAC;CACf;AAUD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,cAAc,EACtB,OAAO,GAAE,qBAA0B,GAClC,qBAAqB,CA0IvB"}
+{"version":3,"file":"process-signals.d.ts","sourceRoot":"","sources":["../../src/server/process-signals.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAQH,OAAO,KAAK,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAGlE;;;;;;;;;GASG;AACH,MAAM,MAAM,iBAAiB,GACzB,QAAQ,GACR,SAAS,GACT,QAAQ,GACR,SAAS,GACT,SAAS,GACT,UAAU,CAAC;AAEf,wDAAwD;AACxD,MAAM,WAAW,cAAc,CAAC,OAAO,GAAG,cAAc;IACtD,QAAQ,CAAC,OAAO,CAAC,EAAE,eAAe,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CACvD;AAED,gEAAgE;AAChE,MAAM,MAAM,wBAAwB,GAAG,SAAS,GAAG,UAAU,GAAG,UAAU,CAAC;AAE3E;;;GAGG;AACH,MAAM,WAAW,YAAY;IAC3B,EAAE,CAAC,MAAM,EAAE,iBAAiB,EAAE,OAAO,EAAE,MAAM,IAAI,GAAG,IAAI,CAAC;IACzD,GAAG,CAAC,MAAM,EAAE,iBAAiB,EAAE,OAAO,EAAE,MAAM,IAAI,GAAG,IAAI,CAAC;IAC1D;;;;;;;;OAQG;IACH,YAAY,CAAC,MAAM,EAAE,iBAAiB,GAAG,OAAO,CAAC;CAClD;AAED,MAAM,WAAW,qBAAqB,CAAC,OAAO,GAAG,cAAc;IAC7D;;;OAGG;IACH,OAAO,CAAC,EAAE,SAAS,iBAAiB,EAAE,CAAC;IACvC;;;;OAIG;IACH,QAAQ,CAAC,EAAE,IAAI,CAAC,eAAe,EAAE,QAAQ,CAAC,CAAC;IAC3C,YAAY,CAAC,EAAE,YAAY,CAAC;IAC5B;;;;;;;;;OASG;IACH,UAAU,CAAC,EAAE,CAAC,MAAM,EAAE,iBAAiB,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACjE;;;;OAIG;IACH,UAAU,CAAC,EAAE,CAAC,MAAM,EAAE,OAAO,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACvD,kEAAkE;IAClE,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,wBAAwB,EAAE,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;IACpE,sFAAsF;IACtF,gBAAgB,CAAC,EAAE,CAAC,MAAM,EAAE,iBAAiB,EAAE,KAAK,EAAE,OAAO,GAAG,UAAU,KAAK,IAAI,CAAC;IACpF;;;;;OAKG;IACH,mBAAmB,CAAC,EAAE,CAAC,MAAM,EAAE,iBAAiB,KAAK,IAAI,CAAC;CAC3D;AAED,MAAM,WAAW,qBAAqB,CAAC,OAAO,GAAG,cAAc;IAC7D;;;;;OAKG;IACH,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC,OAAO,GAAG,SAAS,CAAC,CAAC;IAC/C,wCAAwC;IACxC,KAAK,IAAI,IAAI,CAAC;CACf;AAUD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,GAAG,cAAc,EACzD,MAAM,EAAE,cAAc,CAAC,OAAO,CAAC,EAC/B,OAAO,GAAE,qBAAqB,CAAC,OAAO,CAAM,GAC3C,qBAAqB,CAAC,OAAO,CAAC,CA0IhC"}

package/llms-full.txt

@@ -3744,6 +3744,299 @@ coalescing, collision, stale checkpoint, replay safety, terminal race, compactio
 invariants against any fresh durable adapter.
 
 
+==============================================================================
+# Guide: Managed application kernel  (docs/guide/application-kernel.md)
+==============================================================================
+
+---
+title: Managed application kernel
+description: Compose process-local resources, schedules, readiness, drain and optional provider adapters without building a second job platform.
+type: architecture
+status: active
+created: 2026-08-23
+updated: 2026-08-23
+---
+
+# Managed application kernel
+
+Use `stitchkit/application` when several process-local resources must become
+ready and shut down as one application. Keep using the lower-level server and
+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.
+
+## Minimal composition
+
+```ts
+import {
+  createApplication,
+  createManagedSchedule,
+  defineManagedResource,
+  managedServerResource,
+} from 'stitchkit/application'
+import { bindProcessSignals } from 'stitchkit/server'
+
+const database = defineManagedResource({
+  id: 'database',
+  required: true,
+  start: async ({ signal, reportHealth }) => {
+    await db.connect({ signal })
+    reportHealth('healthy')
+  },
+  close: () => db.disconnect(),
+})
+
+const cleanup = createManagedSchedule({
+  id: 'cleanup',
+  dependsOn: ['database'],
+  everyMs: 60_000,
+  startAfterMs: 60_000,
+  overlap: { mode: 'skip' },
+  errorPolicy: 'continue',
+  run: ({ signal }) => removeExpiredRecords(signal),
+})
+
+const app = createApplication({
+  id: 'service',
+  resources: [
+    database,
+    managedServerResource({ id: 'http', server, dependsOn: ['database'] }),
+    cleanup,
+  ],
+})
+
+const signals = bindProcessSignals(app, {
+  shutdown: { gracePeriodMs: 30_000, forceTimeoutMs: 5_000 },
+  onComplete: (result) => {
+    process.exitCode = result.outcome === 'clean' ? 0 : 1
+  },
+})
+
+await app.start()
+```
+
+The exact resource callbacks are typed by their public configuration. The
+important ownership rule is stable: the application creates and configures the
+database/server/provider objects; Stitchkit orders their process-local
+lifecycle.
+
+## Resource authoring
+
+Give every resource a stable, bounded ID and list its dependencies explicitly.
+The graph is validated before any start. Required resources may depend only on
+required resources; an optional integration cannot silently become a required
+dependency.
+
+Start and readiness are different. A connection can finish setup and return a
+ready handle. A poller can return a handle immediately, settle `ready` later,
+and keep a long-lived `completion` promise. Stitchkit observes both.
+
+Once Stitchkit invokes start/activation, cleanup is guaranteed to be attempted.
+Write `close` so it is safe when setup was partial:
+
+```ts
+let cacheClient: CacheClient | undefined
+
+const cache = defineManagedResource({
+  id: 'cache',
+  required: false,
+  start: async ({ signal, reportHealth }) => {
+    cacheClient = new CacheClient()
+    await cacheClient.connect(signal)
+    reportHealth('healthy')
+  },
+  close: async () => {
+    await cacheClient?.close()
+    cacheClient = undefined
+  },
+})
+```
+
+Invoking `start` makes the descriptor rollback-eligible immediately. Its
+`close` callback must therefore clean side effects even when `start` rejects
+before returning a runtime handle. The kernel calls cleanup once and continues
+cleaning other attempted resources even if one close fails.
+
+## Readiness and health
+
+`await app.start()` resolves only after every required resource is ready and
+every required post-ready activation has succeeded. Lifecycle `ready` is
+published before activation so schedules never arm during `starting`;
+application admission opens only after successful activation. Optional failure
+may retain lifecycle `ready`, but snapshot health is `degraded`, never
+`healthy`.
+
+Readiness is not hidden polling. A resource reports health changes through its
+lifecycle context; the application decides when a database/provider probe runs.
+A required long-lived completion that rejects after startup makes readiness
+false and health unhealthy. Stitchkit records the failure but does not restart
+the resource or process.
+
+`createApplicationHealthHandler` exposes the neutral lifecycle/health snapshot
+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.
+
+## Admission and graceful shutdown
+
+Use the application operation lease for work that is not already counted by a
+managed resource:
+
+```ts
+const operation = app.admission.acquire()
+if (!operation) return Response.json({ error: 'unavailable' }, { status: 503 })
+
+try {
+  await performAcceptedWork()
+} finally {
+  operation.release()
+}
+```
+
+`release()` is idempotent. Admission and counter increment are atomic, so work
+cannot slip between the shutdown check and drain accounting.
+
+Shutdown performs one phase barrier at a time: stop admission everywhere,
+cancel future schedules, drain admitted work, then close in reverse stable
+topological order. Every hook shares the same grace deadline. Forced cleanup
+shares one force deadline. Repeated `shutdown()` calls return the cached promise;
+a repeated process signal forces that same chain.
+
+Do not add a second `process.on('SIGTERM')` handler around the application.
+`bindProcessSignals(app)` is the force/escalation owner. Exit code and hard-exit
+policy remain application/supervisor choices.
+
+## Managed schedules
+
+Schedules activate only after top-level readiness:
+
+```ts
+createManagedSchedule({
+  id: 'reconcile',
+  everyMs: 5_000,
+  startAfterMs: 0,
+  overlap: { mode: 'queue-one' },
+  errorPolicy: 'continue',
+  onError: (error) => internalLogger.error(error),
+  run: ({ signal }) => reconcile(signal),
+})
+```
+
+- `skip` ignores a due tick while one execution is active.
+- `queue-one` retains one successor; additional due ticks coalesce.
+- `parallel` requires `maxConcurrent`; overflow skips rather than creating a
+  hidden queue.
+
+The callback receives the application shutdown signal. Normal shutdown waits
+for admitted executions; force aborts the shared signal. There are no retries,
+cron/timezone rules, persisted cursors, backfill or cross-process locks. Put
+those semantics in a durable application scheduler when they are required.
+Schedule cadence stays monotonic, while status snapshots expose ISO wall-clock
+`capturedAt`, `changedAt` and next/last-run timestamps for portable observation.
+
+## Operational projection
+
+Declare aggregate activity stages, then update them with anonymous handles:
+
+```ts
+const generations = createActivityProjection({
+  id: 'generation',
+  stages: ['queued', 'running', 'finalizing'],
+})
+
+const activity = generations.open('queued', 'queued')
+generations.transition(activity, { stage: 'running', state: 'active' })
+generations.transition(activity, { stage: 'finalizing', state: 'active' })
+generations.complete(activity)
+```
+
+Item identity is deliberately absent from the snapshot. Observers receive
+aggregate counts with application identity, process epoch, revision and
+timestamps. Calling a terminal method twice does not double-count.
+
+```ts
+const sink = createApplicationSnapshotSink({
+  write: (snapshot) => publishOperationalSnapshot(snapshot),
+})
+
+const unsubscribe = generations.subscribe((snapshot) => {
+  sink.publish(snapshot)
+})
+
+// During application cleanup:
+unsubscribe()
+await sink.close()
+```
+
+The sink replays the current absolute value and coalesces obsolete pending
+revisions behind a slow write. Sink failure is observable but cannot fail the
+application operation that changed the projection.
+
+## Optional grammY adapter
+
+Install grammY only in an application that imports the adapter:
+
+```ts
+import { Bot } from 'grammy'
+import {
+  createGrammyWebhookResource,
+  grammyPollingResource,
+} from 'stitchkit/application/grammy'
+```
+
+For simple long polling, pass an already-configured bot:
+
+```ts
+const bot = new Bot(env.BOT_TOKEN)
+bot.command('start', (ctx) => ctx.reply('Hello'))
+bot.catch(({ error }) => internalLogger.error(error))
+
+const telegram = grammyPollingResource({
+  id: 'telegram',
+  bot,
+  required: true,
+})
+```
+
+Readiness follows grammY's `onStart`. Shutdown calls `bot.stop()` once and then
+awaits the retained `bot.start()` promise, because grammY documents that
+`stop()` alone does not wait for middleware completion.
+
+For webhook ingress, `createGrammyWebhookResource` wraps provider-owned update
+handling with admission and drain. The application still mounts the HTTP route,
+verifies/configures its webhook and chooses the grammY framework adapter. An
+update accepted before shutdown may finish; a later update is rejected.
+
+The adapter never reads the token/env, installs commands, changes `bot.catch`,
+chooses retry plugins, drops pending updates, sends outbound messages or stores
+updates. A durable inbox/retry worker remains an application component, not a
+mode of this adapter.
+
+## What disappears from an application
+
+A typical small service can replace roughly 120–220 lines of generic signal,
+timer, admission and close bookkeeping with resource declarations. A larger
+multi-resource service commonly carries 250–450 generic lifecycle lines plus
+15–30 lines for each periodic timer. These are directional review estimates,
+not an API guarantee.
+
+The responsibility change is more important than line count:
+
+| Before | After |
+|---|---|
+| hand-written phase enum and readiness waiters | `createApplication` snapshot |
+| `process.on` signal loop and escalation | `bindProcessSignals(app)` |
+| interval/timeout handles and overlap flag | `createManagedSchedule` |
+| global in-flight counter and drain waiter set | application operation leases |
+| manual stop/close fan-out | resource graph + bounded shutdown |
+| progress delta events | absolute activity projection |
+
+Durable job tables, lifecycle journals/outboxes, provider inboxes and business
+retry rules do **not** disappear. They were never process-local glue and remain
+application-owned.
+
+
 ==============================================================================
 # Guide: CLI  (docs/guide/cli.md)
 ==============================================================================
@@ -8129,6 +8422,92 @@ Also re-exports the error helpers from `stitchkit/contract`.
 
 ---
 
+## `stitchkit/application`
+
+Server-only process-local application composition. See the
+[application kernel guide](../guide/application-kernel.md) and
+[architecture](../architecture/application-kernel.md).
+
+### Kernel and resources
+
+| Export | Kind | Summary |
+|--------|------|---------|
+| `createApplication` | function | compose a validated resource DAG into one non-restartable startup, readiness, admission and shutdown state machine |
+| `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 |
+| `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 |
+
+### Managed schedules
+
+| Export | Kind | Summary |
+|--------|------|---------|
+| `createManagedSchedule` | function | fixed-rate process-local timer that activates after top-level readiness and participates in drain |
+| `ManagedScheduleOverlapSchema` / `ManagedScheduleOverlap` | schema / _type_ | `skip`, `queue-one` or bounded `parallel` overlap policy |
+| `ManagedScheduleErrorPolicySchema` / `ManagedScheduleErrorPolicy` | schema / _type_ | `continue` or `stop-schedule` after an observed callback failure |
+| `ManagedScheduleDescriptorSchema` / `ManagedScheduleDescriptor` | schema / _type_ | immutable public schedule identity and cadence policy |
+| `ManagedScheduleStatusSchema` / `ManagedScheduleStatus` | schema / _type_ | absolute schedule state, revision, counters and timestamps |
+
+Schedule authoring additionally exports `ManagedSchedule`, `ManagedScheduleConfig`,
+`ManagedScheduleRunContext`, `ManagedScheduleClock` and `ManagedScheduleTimer`.
+The clock exposes monotonic cadence/deadline arithmetic and a wall-clock projection for portable
+status timestamps; it is a deterministic test boundary, not a durable scheduler.
+
+### Application and activity projection
+
+| Export | Kind | Summary |
+|--------|------|---------|
+| `createActivityProjection` | function | aggregate anonymous process-local activity into declared bounded stages and absolute snapshots |
+| `createApplicationSnapshotSink` | function | latest-value delivery with one write in flight and one replaceable pending revision |
+| `applicationLifecycleEvent` | function | project a sanitized lifecycle fact from a canonical application snapshot |
+| `createApplicationEventSink` | function | bounded failure-isolated lifecycle-event delivery; events are not canonical state |
+| `ActivitySnapshotSchema` / `ActivitySnapshot` | schema / _type_ | epoch, monotonic revision, timestamps, declared stages and aggregate counts |
+| `ApplicationSnapshotSinkStatusSchema` / `ApplicationSnapshotSinkStatus` | schema / _type_ | immutable latest-value sink delivery and coalescing counters |
+| `ApplicationLifecycleEventSchema` / `ApplicationLifecycleEvent` | schema / _type_ | sanitized operator-facing application lifecycle fact |
+
+Activity authoring additionally exports `ActivityId`, `ActivityIdSchema`,
+`ActivityStageId`, `ActivityStageIdSchema`, `ActivityStageSnapshot`,
+`ActivityStageSnapshotSchema`, `ActivityLiveState`, `ActivityLiveStateSchema`,
+`ActivityProjection`, `ActivityProjectionConfig`,
+`ActivityProjectionSubscriberError`, `ActivityToken` and `ActivityTransition`.
+Latest-value delivery exports `ApplicationSnapshotSink`,
+`ApplicationSnapshotSinkConfig`, `ApplicationSnapshotSinkError` and
+`RevisionedApplicationSnapshot`; event delivery exports `ApplicationEventSink`
+and `ApplicationEventSinkConfig`.
+
+### Canonical application records
+
+The entrypoint exports each Zod schema beside its inferred type:
+`ApplicationIdSchema` / `ApplicationId`, `ApplicationLifecycleSchema` /
+`ApplicationLifecycle`, `ApplicationHealthSchema` / `ApplicationHealth`,
+`ManagedResourceStateSchema` / `ManagedResourceState`,
+`ApplicationAdmissionSnapshotSchema` / `ApplicationAdmissionSnapshot`,
+`ManagedResourceSnapshotSchema` / `ManagedResourceSnapshot`,
+`ApplicationSnapshotSchema` / `ApplicationSnapshot`,
+`ApplicationResourceShutdownSchema` / `ApplicationResourceShutdown`, and
+`ApplicationShutdownResultSchema` / `ApplicationShutdownResult`.
+
+## `stitchkit/application/grammy`
+
+Isolated optional-peer lifecycle adapters. Importing `stitchkit/application`
+does not resolve grammY.
+
+| Export | Kind | Summary |
+|--------|------|---------|
+| `grammyPollingResource` | function | adapt an injected bot's long polling with distinct `onStart` readiness, observed completion and one stop chain |
+| `createGrammyWebhookResource` | function | return a managed resource plus admission-guarded `handleUpdate`; HTTP hosting and webhook registration stay application-owned |
+| `GrammyWebhookUnavailableError` | class | stable `GRAMMY_WEBHOOK_NOT_ACCEPTING` rejection after webhook admission closes |
+| `GrammyPollingResourceConfig` | _type_ | injected bot, polling options, resource graph policy and isolated error observer |
+| `GrammyWebhookResourceConfig` / `GrammyWebhookResource` | _type_ | injected webhook bot declaration and `{ resource, handleUpdate }` handle |
+| `GrammyUpdate` | _type_ | exact update input inferred from the injected grammY bot context |
+
+---
+
 ## `stitchkit/agent-runtime`
 
 Server-only optional application runtime. See the

package/llms.txt

@@ -11,6 +11,7 @@ Build with stitchkit: define a contract once, then `implement` it and serve it (
 - [Typed client](https://github.com/max-listov/stitchkit/blob/master/docs/guide/client.md): createClient/createHttpClient, the typed call surface, scoped clients, SSE
 - [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
 - [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.1",
+  "version": "0.59.2",
   "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",
@@ -84,6 +84,14 @@
       "types": "./dist/agent-runtime-openrouter.d.ts",
       "import": "./dist/agent-runtime-openrouter.js"
     },
+    "./application": {
+      "types": "./dist/application.d.ts",
+      "import": "./dist/application.js"
+    },
+    "./application/grammy": {
+      "types": "./dist/application-grammy.d.ts",
+      "import": "./dist/application-grammy.js"
+    },
     "./testing": {
       "types": "./dist/testing.d.ts",
       "import": "./dist/testing.js"
@@ -103,7 +111,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 --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: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",
@@ -124,6 +132,7 @@
     "@socket.io/component-emitter": "^3.1.2",
     "@tanstack/react-query": ">=5",
     "ai": "^7.0.0",
+    "grammy": "^1.45.1",
     "react": ">=18",
     "react-query-kit": "^3.3.3",
     "socket.io": "^4.8.3",
@@ -156,6 +165,9 @@
     "ai": {
       "optional": true
     },
+    "grammy": {
+      "optional": true
+    },
     "react": {
       "optional": true
     },
@@ -188,6 +200,7 @@
     "@types/react": "^19.2.18",
     "@typescript/typescript6": "^6.0.2",
     "ai": "^7.0.65",
+    "grammy": "^1.45.1",
     "react": "^19.2.8",
     "react-query-kit": "^3.3.4",
     "socket.io": "^4.8.3",