stitchkit 0.93.0 → 0.94.1

package/llms/application-diagnostic-journal.txt

@@ -0,0 +1,30 @@
+# stitchkit/application/diagnostic-journal — stitchkit docs slice
+
+> Generated from the `docs/` tree by `bun run gen:llms`. The index of all slices is
+> `llms.txt` in this package.
+
+Contains: API reference: `stitchkit/application/diagnostic-journal`  (docs/api/reference.md)
+
+Also read:
+- see `llms/application.txt` for the Managed application kernel guide
+
+==============================================================================
+# API reference: `stitchkit/application/diagnostic-journal`  (docs/api/reference.md)
+==============================================================================
+
+## `stitchkit/application/diagnostic-journal`
+
+| Export | Kind | Summary |
+|--------|------|---------|
+| `createDiagnosticJournal` | function | the bounded local journal: a file lock, a spawn to diagnose a stale one, and framed writes |
+
+Its own entrypoint because of what it reaches — `node:child_process`,
+`node:fs`, `node:os`, `node:util` — with `promisify(execFile)` evaluated while
+the module initialises. Exported from `stitchkit/application`, that one line made
+the entire barrel unusable in a browser bundle: not by failing at the call, but
+by throwing during module initialisation, on every route.
+
+Its **contract** stays in `stitchkit/application` — every
+`DiagnosticJournal*Schema`, the states and the refusal reasons touch nothing but
+Zod, and a client reading a journal's status has as much right to them as the
+server writing it.

package/llms/application-grammy.txt

@@ -0,0 +1,27 @@
+# stitchkit/application/grammy — stitchkit docs slice
+
+> Generated from the `docs/` tree by `bun run gen:llms`. The index of all slices is
+> `llms.txt` in this package.
+
+Contains: API reference: `stitchkit/application/grammy`  (docs/api/reference.md)
+
+Also read:
+- see `llms/application.txt` for the Managed application kernel guide
+
+==============================================================================
+# API reference: `stitchkit/application/grammy`  (docs/api/reference.md)
+==============================================================================
+
+## `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 |

package/llms/application-opentelemetry.txt

@@ -0,0 +1,27 @@
+# stitchkit/application/opentelemetry — stitchkit docs slice
+
+> Generated from the `docs/` tree by `bun run gen:llms`. The index of all slices is
+> `llms.txt` in this package.
+
+Contains: API reference: `stitchkit/application/opentelemetry`  (docs/api/reference.md)
+
+Also read:
+- see `llms/application.txt` for the Managed application kernel guide
+
+==============================================================================
+# API reference: `stitchkit/application/opentelemetry`  (docs/api/reference.md)
+==============================================================================
+
+## `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 |

package/llms/application-schemas.txt

@@ -0,0 +1,42 @@
+# stitchkit/application/schemas — stitchkit docs slice
+
+> Generated from the `docs/` tree by `bun run gen:llms`. The index of all slices is
+> `llms.txt` in this package.
+
+Contains: API reference: `stitchkit/application/schemas`  (docs/api/reference.md)
+
+Also read:
+- see `llms/application.txt` for the Managed application kernel guide
+
+==============================================================================
+# API reference: `stitchkit/application/schemas`  (docs/api/reference.md)
+==============================================================================
+
+## `stitchkit/application/schemas`
+
+The canonical application records — and nothing else. Every export here is also
+reachable from `stitchkit/application`; the difference is what comes with it.
+
+`stitchkit/application` is the server runtime: it reaches `node:child_process`,
+`node:fs` and `node:crypto`. A browser bundler does not omit those, it
+substitutes stubs — so a module that merely *names* an application schema fails
+while it is initialising, and the page never mounts, on every route rather than
+the one that wanted the schema. A contract whose `output` is an application
+snapshot could be declared and never consumed, which is the one thing a contract
+is for.
+
+So the same schemas ship a second way, from a module with nothing behind them:
+
+```ts
+// browser and server alike
+import { ApplicationSnapshotSchema } from 'stitchkit/application/schemas';
+```
+
+The exports are exactly those listed under
+[canonical application records](#canonical-application-records) above.
+`packages/core/scripts/check-browser-clean.mjs` holds the promise against the
+built artifact: it walks the browser lane's real `dist` output and refuses a
+`node:` import reachable from any of it, and refuses an entry built for the
+browser that no `exports` path leads to — which is how this one was missing.
+
+---

package/llms/application.2.txt

@@ -0,0 +1,487 @@
+# stitchkit/application — stitchkit docs slice, part 2 of 2
+
+> Generated from the `docs/` tree by `bun run gen:llms`. The index of all slices is
+> `llms.txt` in this package.
+
+Parts of this slice:
+- `llms/application.txt`: Guide: Managed application kernel  (docs/guide/application-kernel.md)
+- `llms/application.2.txt`: Guide: Application migration recipes  (docs/guide/application-migration-recipes.md) · API reference: `stitchkit/application`  (docs/api/reference.md)
+
+==============================================================================
+# 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.
+
+## Bound a handler and a local worker with one lease policy
+
+Use a bounded admission when two entry paths consume the same finite local
+capacity. Composing it with `application.admission` keeps readiness and shutdown
+as the upstream gate:
+
+```ts
+const work = createBoundedAdmission({
+  upstream: app.admission,
+  policy: {
+    global: { maxConcurrent: 4 },
+    perKey: { maxConcurrent: 1, maxKeys: 1_000 },
+  },
+})
+
+const fromHttp = (key: string, signal: AbortSignal) =>
+  work.run(key, (context) => render(context.signal), { signal, timeoutMs: 20_000 })
+
+const fromWorker = (key: string) =>
+  work.run(key, (context) => reconcile(context.signal))
+```
+
+A timeout in `fromHttp` does not free a permit while `render` remains active.
+At shutdown call `work.stopAdmission()` with the other admission owners and
+await `work.drain(...)`; the result reports the actual remainder.
+
+## Replace ad-hoc output and progress queues
+
+Ordered output and replaceable progress are separate declarations:
+
+```ts
+const lines = createBoundedChannel<string>({
+  policy: 'ordered', maxItems: 100, maxBytes: 1_000_000,
+  sizeOf: (line) => new TextEncoder().encode(line).byteLength,
+})
+
+const state = createBoundedChannel<{ revision: number; percent: number }>({
+  policy: 'latest', maxItems: 1, maxBytes: 64,
+  sizeOf: () => 64,
+})
+
+const lineResult = lines.offer('one durable-in-process ordering unit')
+const stateResult = state.offer({ revision: 2, percent: 50 })
+```
+
+Handle `refused` from `lines` at the protocol boundary; do not turn it into
+implicit loss. A `coalesced` state result is expected latest-value behaviour,
+not evidence that an ordered event was delivered. Neither channel is durable;
+persist first when restart replay is required.
+
+## Handing a handle to the resources that depend on it
+
+`dependsOn` carries ordering. To carry the object as well, return a `value` from
+`start` and read it with `context.use(...)`. This replaces the module-local
+`let handle: T | null` with the guard the graph makes unreachable.
+
+```ts
+const database = defineManagedResource({
+  id: 'database',
+  start: async () => ({ value: await connect(env.DATABASE_URL) }),
+})
+
+const worker = defineManagedResource({
+  id: 'worker',
+  dependsOn: [database],
+  start(context) {
+    const db = context.use(database)   // Connection — not Connection | null
+  },
+})
+```
+
+Declare the dependency with the **resource** whenever you intend to read from
+it: that is the form `use` can type, and it stops the declaration and the read
+from drifting. A string still expresses order on its own.
+
+The value is published when `start` resolves and stays readable from `activate`
+and from the shutdown phases. `use` refuses a resource that was not declared in
+`dependsOn` — that only ever worked by luck of declaration order — and refuses a
+resource that published nothing, which the compiler refuses too. The executable
+recipe proves both the read and the refusal.
+
+## Managed HTTP server
+
+The main resource of a web backend, and the one whose ownership rule is
+counter-intuitive: give `managedServerResource` a **thunk** and it creates the
+server during `start`, after its dependencies are ready. Give it an
+already-listening server and it adopts that one instead.
+
+```ts
+const http = managedServerResource({
+  id: 'http',
+  dependsOn: [database],
+  server: (context) => {
+    const db = context.use(database)
+    return createServer({ port: env.PORT, services: createServices(db) })
+  },
+})
+
+const app = createApplication({ id: 'service', resources: [database, http] })
+await app.start()   // the port is bound; the snapshot means it
+```
+
+The server resource publishes its `ManagedServerHandle`, so anything that needs
+the running server — a Socket.IO attachment, a URL to log, a probe — reads it
+with `context.use(http)` rather than through a module-local.
+
+The factory itself receives `ManagedResourceContext` too. It can read only the
+dependencies declared on the server resource and shares the graph's startup
+signal. A dependency failure prevents the factory from binding; a factory
+rejection is rolled back without invoking the factory a second time.
+
+Do not spread this resource over your own `start` to control creation order:
+that shape exists only as a workaround for the version whose `start` was empty,
+and `dependsOn` now expresses the order directly. The executable recipe binds a
+real port, proves a request reaches it after `start()` resolves, and proves the
+port is closed after `shutdown()`.
+
+## 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.
+
+==============================================================================
+# API reference: `stitchkit/application`  (docs/api/reference.md)
+==============================================================================
+
+## `stitchkit/application`
+
+Server-only process-local application composition. See the
+[application kernel guide](../guide/application-kernel.md) and
+[architecture](../architecture/application-kernel.md). Complete consumer
+cutovers are covered by the executable
+[migration recipes](../guide/application-migration-recipes.md).
+
+### Kernel and resources
+
+| Export | Kind | Summary |
+|--------|------|---------|
+| `createApplication` | function | compose a validated resource DAG into one startup, readiness, admission and shutdown state machine |
+| `StateStore` / `StateStoreUpdate` | _type_ | async atomic read/update boundary shared by durable application state machines |
+| `createProcessLifecycleLedger` / `ProcessLifecycleLedger` / `ProcessLifecycleLedgerConfig` | function / _type_ | durable bounded run history and typed fact subscription |
+| `LifecycleRunSchema` / `LifecycleRun` / `LifecycleStateSchema` / `LifecycleState` / `LifecycleTerminationSchema` / `LifecycleTermination` | schema / _type_ | versioned process-run state and termination vocabulary |
+| `PreviousExitSchema` / `PreviousExit` / `StartFact` / `ReadyFact` / `ShutdownFact` / `ProcessLifecycleFact` | schema / _type_ | first-boot, hot-reload, clean, forced, handoff and abnormal lifecycle facts |
+| `transitionProcessStart` / `transitionProcessReady` / `transitionProcessShutdown` | function | pure idempotent runId+pid-owned transitions |
+| `LifecycleTransition` / `TransitionStartInput` / `TransitionReadyInput` / `TransitionShutdownInput` / `SameVersionOverlap` | _type_ | pure transition inputs, the same-build overlap policy (`abnormal` default / `handoff`) and state+fact result |
+| `lifecycleLedgerResource` / `LifecycleLedgerResource` / `LifecycleLedgerResourceConfig` | function / _type_ | managed-resource adapter that records start, readiness and shutdown |
+| `createNotificationOutbox` / `NotificationOutbox` / `NotificationOutboxConfig` | function / _type_ | bounded at-least-once queue with durable claims, leases, retries and supersede |
+| `NotificationOutboxItem` / `NotificationOutboxReceipt` / `NotificationOutboxState` / `NotificationSend` / `NotificationFailureClassification` / `DroppedNotification` / `EnqueueNotification` | _type_ | versioned queue records, stable send identity and delivery decisions |
+| `notificationOutboxStateSchema` | function | strict persisted-state schema over an application payload schema |
+| `notificationOutboxResource` / `NotificationOutboxResource` / `NotificationOutboxResourceConfig` | function / _type_ | thin managed-resource scheduler over an outbox handle |
+| `ApplicationHandle.restart` | method | replace one resource and everything that depends on it, leaving the rest of the graph running and the process epoch unchanged |
+| `ApplicationRestartInputSchema` / `ApplicationRestartInput` | schema / _type_ | the resource to replace, by id, and optionally `gracePeriodMs` / `forceTimeoutMs` for this restart — the application's own shutdown budget otherwise |
+| `ApplicationRestartResultSchema` / `ApplicationRestartResult` | schema / _type_ | the subtree that was actually taken down and brought back, in start order, with the outcome, the reason on anything but success, and how long it took |
+| `ApplicationRestartOutcomeSchema` / `ApplicationRestartOutcome` | schema / _type_ | `restarted`, `failed` or `refused` — a refusal (unknown id, shutting down, not yet ready) is not a failure and touches nothing |
+| `ApplicationResourceFailure` | _type_ | one resource failure with the cause its phase label cannot carry — delivered to `onResourceFailure` |
+| `ApplicationResourcePhase` | _type_ | the phase a managed resource failed in — the vocabulary of `ApplicationResourceShutdown.failures` |
+| `ApplicationShutdownOptionsSchema` / `ApplicationShutdownOptions` | schema / _type_ | the two shutdown budgets and an abort signal — without the HTTP-only `retryAfterSeconds` |
+| `ApplicationShutdownBudgetSchema` / `ApplicationShutdownBudget` | schema / _type_ | the same two budgets without a signal — `ApplicationConfig.shutdown`, the default for `shutdown()` and the only budget a failed startup's rollback can read |
+| `ActivityTokenBrand` | const | the brand symbol `ActivityToken` carries, exported so `ActivityProjection` is implementable |
+| `defineManagedResource` | function | retain the exact typed resource declaration; every invoked start is rollback-eligible |
+| `managedServerResource` | function | own a managed server's lifecycle without copying its HTTP/WebSocket shutdown machine — a thunk is called during `start`, and the handle is published to dependants |
+| `managedResourceDependencyId` | function | the id of a dependency declared either as a string or as the resource itself |
+| `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, separate readiness/completion promises and the value a resource publishes to its dependants |
+| `ManagedResourceDependency` | _type_ | a dependency named by id or given as the resource itself — the second form is what `context.use(...)` can type |
+| `ManagedResourcePublished` | _type_ | the value type `context.use(resource)` returns, recovered from that resource's own `start` |
+| `ManagedResourcePublishesNoValue` | _type_ | what `context.use(...)` returns for a resource that publishes nothing — a branded refusal rather than `never`, so reading it does not silently compile |
+| `ManagedServerResourceConfig` | _type_ | the server or a sync/async factory receiving `ManagedResourceContext`, plus stable ID, dependencies and server shutdown policy (`retryAfterSeconds`, `realtimeCloseTimeoutMs`) |
+| `ManagedServerResource` | _type_ | the resource `managedServerResource` returns, whose `start` publishes the `ManagedServerHandle` |
+| `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 |
+
+### Bounded admission
+
+| 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`, 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 |
+| `BoundedAdmissionSnapshotSchema` / `BoundedAdmissionSnapshot` | schema / _type_ | absolute active/lifetime/refusal/rate-accounting counters |
+| `BoundedAdmission` / `BoundedAdmissionConfig` / `BoundedAdmissionClock` | _type_ | handle, policy/upstream/clock configuration and monotonic clock seam |
+| `BoundedAdmissionResult` / `BoundedAdmissionLeaseResult` / `BoundedAdmissionRefusedResult` | _type_ | explicit leased-or-refused acquisition result; retry time exists only for rate bounds |
+| `BoundedOperationLease` | _type_ | idempotent release lease, optionally carrying its key |
+| `BoundedOperationRunContext` / `BoundedOperationRunOptions` | _type_ | underlying work signal and caller abort/timeout wait budget |
+| `BoundedAdmissionDrainOptions` / `BoundedAdmissionDrainResult` / `BoundedAdmissionForceResult` | _type_ | bounded drain inputs and honest remaining-work results |
+| `BoundedAdmissionRefusalError` | class | `run()` refusal with reason and optional `retryAfterMs` |
+| `BoundedOperationWaitError` | class | caller wait ended as `cancelled` or `timed-out`; underlying capacity remains leased until work settles |
+
+### Revision wake-up
+
+| Export | Kind | Summary |
+|--------|------|---------|
+| `createRevisionSignal` | function | finite broadcast wait for the next monotonic process-local revision |
+| `RevisionSignal` / `RevisionSignalConfig` / `RevisionSignalClock` / `RevisionSignalTimer` | _type_ | signal handle, waiter bound and replaceable timer boundary |
+| `RevisionSignalWaitOptions` | _type_ | optional caller `signal` and positive `timeoutMs`; absent options wait until advance or close |
+| `RevisionSignalWaitOutcomeSchema` / `RevisionSignalWaitOutcome` | schema / _type_ | `changed \| timed-out \| aborted \| closed \| capacity` |
+| `RevisionSignalWaitResultSchema` / `RevisionSignalWaitResult` | schema / _type_ | terminal wait outcome with the revision observed at settlement |
+| `RevisionSignalAdvanceResultSchema` / `RevisionSignalAdvanceResult` | schema / _type_ | successful `advanced` or post-close `closed`, with the resulting revision |
+| `RevisionSignalStateSchema` / `RevisionSignalState` | schema / _type_ | `open \| closed` lifecycle |
+| `RevisionSignalSnapshotSchema` / `RevisionSignalSnapshot` | schema / _type_ | current revision, finite pending count and lifetime outcome counters |
+
+### Bounded delivery
+
+| Export | Kind | Summary |
+|--------|------|---------|
+| `createBoundedChannel` | function | finite single-reader async channel with explicit ordered or latest-value policy |
+| `BoundedChannelPolicySchema` / `BoundedChannelPolicy` | schema / _type_ | `ordered \| latest` retention policy |
+| `BoundedChannelStateSchema` / `BoundedChannelState` | schema / _type_ | `open \| draining \| closed \| failed` |
+| `BoundedChannelSnapshotSchema` / `BoundedChannelSnapshot` | schema / _type_ | exact retained count/bytes, waiter and outcome counters |
+| `BoundedChannel` / `BoundedChannelConfig` / `BoundedChannelCloseOptions` | _type_ | iterator/offer handle, explicit count/byte/size policy and drain/discard close mode |
+| `BoundedChannelOfferResult` | _type_ | `delivered`, `queued`, `coalesced`, or reasoned `refused` outcome |
+| `BoundedChannelReaderError` | class | refusal of a second concurrent pending `next()` |
+| `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
+
+| Export | Kind | Summary |
+|--------|------|---------|
+| `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 |
+| `readDiagnosticJournalLockDiagnosis` / `DiagnosticJournalLockDiagnosis` | function / _type_ | why a `reclaim-stale` acquisition refused — owner alive, another machine, or a lock this host cannot attribute — read off the thrown `EEXIST` |
+| `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 |
+| `DiagnosticJournalWaitResultSchema` / `DiagnosticJournalWaitResult` | schema / _type_ | flush settlement boundary with truthful settled, timed-out or cancelled result |
+| `DiagnosticJournalCloseResultSchema` / `DiagnosticJournalCloseResult` | schema / _type_ | physical close or caller timeout/cancellation without pretending an active write stopped |
+| `DiagnosticJournalStateSchema` / `DiagnosticJournalState` | schema / _type_ | `open \| draining \| closed \| failed` |
+| `DiagnosticJournalRefusalReasonSchema` / `DiagnosticJournalRefusalReason` | schema / _type_ | `closed \| failed \| invalid \| oversized \| item-capacity \| byte-capacity` |
+| `DiagnosticJournalFailurePhaseSchema` / `DiagnosticJournalFailurePhase` | schema / _type_ | internal `write \| rotation \| close` failure phase exposed only to status and the isolated observer |
+| `DiagnosticJournalWaitOptions` / `DiagnosticJournalFailure` | _type_ | caller wait signal/timeout and isolated internal failure callback record |
+
+`accepted` is bounded in-memory admission and `written` is completed append, not `fsync` or durable
+delivery. The journal has no reader/replay/upload API. See the
+[guide](../guide/application-kernel.md#bounded-local-diagnostic-journal),
+[architecture](../architecture/diagnostic-journal.md) and [ADR
+0134](../decisions/0134-diagnostic-journal-is-bounded-local-evidence.md).
+
+### 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
+
+These are also published on their own as
+[`stitchkit/application/schemas`](#stitchkitapplicationschemas), which carries
+no server runtime and can therefore be imported from a browser bundle.
+
+The entrypoint exports each Zod schema beside its inferred type:
+`ApplicationIdSchema` / `ApplicationId`, `ApplicationLifecycleSchema` /
+`ApplicationLifecycle`, `ApplicationHealthSchema` / `ApplicationHealth`,
+`ManagedResourceStateSchema` / `ManagedResourceState`,
+`ApplicationAdmissionSnapshotSchema` / `ApplicationAdmissionSnapshot`,
+`ManagedResourceSnapshotSchema` / `ManagedResourceSnapshot`,
+`ApplicationSnapshotSchema` / `ApplicationSnapshot`,
+`ApplicationStatusProjectionSchema` / `ApplicationStatusProjection` with
+`projectApplicationStatus` — what a status or probe endpoint may publish, and
+the function that derives it from a snapshot,
+`ApplicationResourceShutdownSchema` / `ApplicationResourceShutdown`, and
+`ApplicationShutdownResultSchema` / `ApplicationShutdownResult`.
+
+### Decisions
+
+A pipeline of policies that each vote `allow`, `deny` or `defer`, sharing its
+vocabulary with an event topic declared `mode: 'decision'`.
+
+| Export | Kind | Summary |
+|--------|------|---------|
+| `createDecisionPipeline` | function | run policies in declaration order; the first terminal verdict wins and the rest do not run |
+| `DecisionPipelineConfig` | _type_ | `policyTimeoutMs` — how long one policy has to answer. Required, no default: a policy that never settles hangs every caller of the operation it guards |
+| `PolicyDecisionSchema` / `PolicyDecision` | schema / _type_ | `allow`, `deny` with a reason, or `defer` — a deny cannot be silent |
+| `DecisionPolicy` / `DecisionPipeline` | _types_ | one named voter over the caller's subject, and the pipeline it composes into |
+| `DecisionResult` / `DecisionTraceEntry` | _types_ | the verdict, and the trace of what actually ran — not what was declared |
+| `DecisionUndecidedError` | class | every policy deferred and no undecided outcome was declared: an unanswered question, raised rather than guessed |
+| `DecisionPolicyError` | class | a policy returned a non-decision, threw, or ran past `policyTimeoutMs` — one error for all three, carrying the policy id and the trace so far |
+
+### Keyspace and watched reads
+
+| Export | Kind | Summary |
+|--------|------|---------|
+| `defineKeyspace` / `keyspaceResource` | function | a named record set read synchronously from memory and written through one serialised chain; backend first, then memory, then the change event |
+| `openKeyspace` / `OpenedKeyspace` | function / type | the same keyspace opened directly, for an application that owns its own lifecycle rather than declaring resources to a kernel |
+| `KeyspaceBackend` / `KeyspaceDeclaration` / `KeyspaceChange` / `KeyspaceResourceConfig` / `OpenKeyspace` | _types_ | the four-method durability port, the declaration, the announced change, the resource's options and the published handle. `backend` takes a value or a **factory** — a factory is called once per generation, so a restarted keyspace gets a backend that was never closed |
+| `memoryKeyspaceBackend` / `sqliteKeyspaceBackend` / `SqliteKeyspaceBackendConfig` | function / type | a disposable in-process backend, and one table with a key and a JSON payload over a caller-owned database |
+| `SqliteDatabase` / `SqliteStatement` / `SqliteValue` | _types_ | the minimal synchronous SQLite boundary the framework types against |
+| `createWatchHub` / `watchKey` | function | one read per question however many are asking: single-flight per key, re-read on a declared topic, publish only what changed |
+| `WatchHub` / `WatchHubConfig` / `WatchOperation` / `WatchSubscriber` / `AttachedWatcher` | _types_ | the hub, its read/watchable/invalidation policy, the operation identity, and one connection's attachment |
+
+→ [ADR 0152](../decisions/0152-a-keyspace-is-memory-that-nothing-reaches-before-it-is-durable.md),
+[ADR 0153](../decisions/0153-a-watched-read-is-one-read-per-question.md).