stitchkit 0.101.3 → 0.103.0

package/llms/application.3.txt

@@ -0,0 +1,278 @@
+# stitchkit/application — stitchkit docs slice, part 3 of 3
+
+> 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: Managed application kernel  (docs/guide/application-kernel.md) · Guide: Application migration recipes  (docs/guide/application-migration-recipes.md)
+- `llms/application.3.txt`: API reference: `stitchkit/application`  (docs/api/reference.md)
+
+==============================================================================
+# 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 — open (`active`, `draining` with `unavailableAt`) and ended (`clean`, `forced`, `startup-failed`, `hot-reload`, `abnormal`) |
+| `PreviousExitSchema` / `PreviousExit` / `StartFact` / `ReadyFact` / `DrainingFact` / `ShutdownFact` / `ProcessLifecycleFact` | schema / _type_ | first-boot, hot-reload, clean, forced, startup-failed, handoff and abnormal lifecycle facts; `processGapMs` on start, `downtimeMs` (unavailable → ready) on ready |
+| `transitionProcessStart` / `transitionProcessReady` / `transitionProcessDraining` / `transitionProcessShutdown` | function | pure idempotent runId+pid-owned transitions |
+| `LifecycleTransition` / `TransitionStartInput` / `TransitionRunInput` / `TransitionShutdownInput` / `SameVersionOverlap` / `VersionChangeOverlap` | _type_ | pure transition inputs (`TransitionRunInput` for ready and draining, extended with `forced` for shutdown), the same-build overlap policy (`abnormal` default / `handoff`), the version-change overlap policy (`handoff` default / `abnormal`) and state+fact result |
+| `lifecycleLedgerResource` / `LifecycleLedgerResource` / `LifecycleLedgerResourceConfig` | function / _type_ | managed-resource adapter that records start, readiness, admission stop (draining) 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 |
+| `createDirectoryInbox` (from `stitchkit/application/directory-inbox`) / `DirectoryInbox` / `DirectoryInboxConfig` / `DirectoryInboxDelivery` / `DirectoryInboxResource` | function / _type_ | managed resource delivering each `<name>.json` entry another program drops into a directory to the application at least once, after readiness; separate durable taken/done records, leases, bounded retry |
+| `DirectoryInboxStateSchema` / `DirectoryInboxState` / `DirectoryInboxRejection` / `DirectoryInboxRejectionReasonSchema` / `DirectoryInboxRejectionReason` | schema / _type_ | the inbox's claims, receipts and rejections (`invalid`, `too-large`, `attempt-limit`) |
+| `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 |
+| `ManagedResourceAdmission` | _type_ | `context.admission`: `acquire()` now or `null`, and `acquireWhenAccepting(signal)` for a resource that fetches work — a poller waits instead of fetching while the application is starting or degraded; rejects on abort and once the application can no longer admit |
+| `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 — attribution, PID liveness and optional process `identity` evidence (`matched`, `different-boot`, `reused-pid`, `pid-gone`, `legacy`, `unavailable`) — 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 |
+| `DiagnosticJournalAnomalySchema` / `DiagnosticJournalAnomaly` | schema / _type_ | corrupt-row reason, file, zero-based byte offset, one-based line, tail/interior position and skipped bytes |
+| `createDiagnosticJournalReadResultSchema` / `DiagnosticJournalReadResult` | function / _type_ | owner-schema frame output or explicit anomaly; retains transformed event output types |
+| `DiagnosticJournalRecoveryStatusSchema` / `DiagnosticJournalRecoveryStatus` | schema / _type_ | bounded startup inspection counts and first/last anomaly locations |
+| `DiagnosticJournalRecoveryError` | class | torn single-file startup refusal carrying recovery observations, preserving evidence and releasing its lock |
+
+`accepted` is bounded in-memory admission and `written` is completed append, not `fsync` or durable
+delivery. Its filesystem reader is in the diagnostic-journal leaf; there is no managed 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).
+
+### Managed change subscriptions and scoped watches
+
+`changeSubscriptionResource` (`stitchkit/application`) accepts
+`ChangeSubscriptionConfig`: `id`, unique `keys` (1–128, at most 256 characters each),
+`connect(signal)`, `reconcile(key, context)`, required `reconcileIntervalMs` (10 ms–1 h),
+optional `timeoutMs` (30000; 1 ms–1 h), `backoff`, and `onError`.
+`ChangeConnection` supplies `subscribe({ signal, hint, disconnected })`, which completes subscription
+before the first read; `close()` releases it. `ChangeReconciliation` exposes `signal`
+and a synchronous `commit(callback)` guard against late publication. Drivers must
+honor cancellation. Uncooperative work retains its slot until settled instead of
+allowing overlapping connections/reads. Errors reach `onError`; no raw payload or
+connection string is logged by this resource. Recovery runs after reconnect and
+periodically even when no notification arrives.
+
+`WatchHubConfig` adds `maxSources` (1024), `maxSubscribers` (1024), and optional
+`reconcileIntervalMs` (10 ms–1 h). `hub.attach(subscriber, scope?)` accepts a
+`WatchAdmissionScope` containing a **server-verified** `key` (1–512 characters) and
+revocation `signal`. The key separates sharing and is the optional third argument
+of `read(operation, args, scope)`; a key's `instance` routes frames and never
+separates sources. Attached over `maxSubscribers`, a subscriber gets a watcher whose
+`open` refuses with `Watch subscriber capacity exceeded`; `attach` does not throw
+for capacity. It must represent account, session and permissions;
+never trust a client-supplied owner ID as that scope.
+
+
+
+### Notification action and projection receipts
+
+`NotificationOutboxConfig.delivery` accepts `NotificationDeliveryConfig`:
+immutable executor `version`, pure `actions(payload)` plan selector (1–128 unique
+names, each at most 128 characters), and idempotent `project(notification, receipts)`.
+`send` receives optional `action` and stable `idempotencyKey`, and returns a JSON
+remote receipt (void becomes null). A result that is not JSON or does not fit the
+byte budget is kept as `receipt: null` with `unrecorded: 'not-json' | 'too-large'`;
+the action stays confirmed and is not sent again. `retiredVersions` maps earlier
+plan versions to their `NotificationProjection` so queued items drain after an
+executor upgrade; an unknown version is reported to `onError` as
+`NotificationPlanVersionError` and waits, spending no attempt and not consulting
+`classify`, for an executor that knows it. `NotificationDeliveryStateSchema` validates the
+optional `NotificationDeliveryState` on queued items and completed receipts:
+`version`, `actions`, `receipts` and optional `projectedAt`. Checkpoints share the
+existing atomic StateStore and lease fence. Receipt retention and serialized byte
+budgets still apply. Single-send configuration remains valid without `delivery`.
+A remote result lost before its checkpoint may be sent again; provider idempotency
+or reconciliation is required. A projection may repeat after a crash before its
+checkpoint. Business-transaction enqueue and durable quarantine are not implied.

package/llms/application.txt

@@ -1,4 +1,4 @@
-# stitchkit/application — stitchkit docs slice, part 1 of 2
+# stitchkit/application — stitchkit docs slice, part 1 of 3
 
 > Generated from the `docs/` tree by `bun run gen:llms`. The index of all slices is
 > `llms.txt` in this package.
@@ -6,7 +6,8 @@
 
 Parts of this slice:
 - `llms/application.txt`: Guide: Managed application kernel  (docs/guide/application-kernel.md)
-- `llms/application.2.txt`: Guide: Managed application kernel  (docs/guide/application-kernel.md) · Guide: Application migration recipes  (docs/guide/application-migration-recipes.md) · API reference: `stitchkit/application`  (docs/api/reference.md)
+- `llms/application.2.txt`: Guide: Managed application kernel  (docs/guide/application-kernel.md) · Guide: Application migration recipes  (docs/guide/application-migration-recipes.md)
+- `llms/application.3.txt`: API reference: `stitchkit/application`  (docs/api/reference.md)
 
 ==============================================================================
 # Guide: Managed application kernel  (docs/guide/application-kernel.md)
@@ -18,7 +19,7 @@ description: Compose process-local resources, schedules, readiness, drain and op
 type: architecture
 status: active
 created: 2026-08-23
-updated: 2026-09-04 14:11 +07:00
+updated: 2026-09-30 17:41 +07:00
 ---
 
 # Managed application kernel
@@ -665,10 +666,47 @@ short-lived reclaim guard.
 
 `flush()` means every accepted append through that call's boundary settled. It is not `fsync`, a
 durable receipt, exactly-once execution or remote delivery. Timeout/cancellation bound only the
-waiter; the writer retains physical capacity until settlement. There is no reader or upload API.
-Use a durable application store or deployment-owned log collector when restart recovery, replay or
+waiter; the writer retains physical capacity until settlement. There is no upload or managed replay API.
+Use a durable application store or deployment-owned log collector when durable restart recovery, replay or
 aggregation is required. → [ADR 0134](../decisions/0134-diagnostic-journal-is-bounded-local-evidence.md).
 
+For finite inspection, use the shared reader with an explicit oldest-to-newest list of existing
+files. Keep anomaly reporting outside the journal being inspected:
+
+```ts
+import { readDiagnosticJournal } from 'stitchkit/application/diagnostic-journal'
+import { z } from 'zod'
+
+const eventSchema = z.object({
+  kind: z.enum(['resource_failed', 'recovery_started']),
+  resource: z.string().max(80),
+}).strict()
+
+for await (const row of readDiagnosticJournal({
+  paths: ['/var/lib/example/diagnostic.jsonl.1', '/var/lib/example/diagnostic.jsonl'],
+  eventSchema,
+  maxLineBytes: 4 * 1024,
+})) {
+  if (row.type === 'anomaly') internalLogger.warn(row.anomaly)
+  else inspectEvent(row.frame.event)
+}
+```
+
+The reader bounds memory by line size plus a fixed chunk, skips oversized/damaged rows with
+explicit anomalies, and still returns valid rows before and after them. `offset` is zero-based
+bytes; `line` is one-based. `position` distinguishes the file's tail from interior damage.
+A valid frame lacking its final LF yields a warning with `skippedBytes: 0` and its frame.
+Each file's size is captured at open; concurrent appends are excluded. Missing files, permissions,
+symlinks, non-regular files and mid-read truncation throw rather than masquerading as bad data.
+The caller owns file selection and coordination with an active rotator.
+
+Writer startup inspects retained and active files under its lock. On damage,
+`journal.getStatus().recovery` contains counts and first/last anomaly locations, reconstructed
+again on restart from the preserved bytes. This describes startup observations, not live
+continuous inspection. `maxFiles: 1` cannot preserve a torn active file by rotation and throws
+`DiagnosticJournalRecoveryError` before removing any evidence; configure at least two slots.
+Normal rotation retains the existing finite eviction policy. → [ADR 0219](../decisions/0219-journal-damage-is-data-and-io-failure-is-failure.md).
+
 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
@@ -854,156 +892,3 @@ The responsibility change is more important than line count:
 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.
-
-## Durable process facts and owner notifications
-
-`createProcessLifecycleLedger` records a bounded versioned list of process runs.
-Start, readiness, draining and shutdown target both `runId` and `pid`, so hot
-reload and PID reuse cannot close the wrong generation. `lifecycleLedgerResource`
-drives it from the kernel's phases: `start` records the start, `activate` the
-readiness, `stopAdmission` the drain — the run's `unavailableAt`, the moment it
-stops answering new work — and `close` / `force` the stop. A run that stops
-without ever becoming ready (a failed startup rolls back with `close` only)
-ends as `startup-failed`, not `clean`.
-
-A start classifies what happened to the newest run before it, and the
-classification is decided by four facts — whether that run recorded its own
-exit, whether the pid is the same, whether the version changed and whether it
-ever became ready:
-
-| newest run | same pid | version | `previousExit` | predecessor's `termination` |
-|---|---|---|---|---|
-| none | — | — | `first-boot` | — |
-| recorded `stoppedAt` | — | — | `clean` / `forced` / `startup-failed` / `abnormal` as recorded | unchanged |
-| still open | yes | — | `hot-reload` | `hot-reload`, closed at the new start |
-| still open | no | changed | `handoff` (default) | stays open; it records its own stop later |
-| still open | no | changed, `versionChangeOverlap: 'abnormal'` | `abnormal` / `startup-failed` | closed at the new start, as for the same version |
-| still open, was ready | no | same | `abnormal` (default) | `abnormal`, closed at the new start — an upper bound, the crash time is unknown |
-| still open, never ready | no | same | `startup-failed` (default) | `startup-failed`, closed at the new start |
-
-Every other open run the start finds was abandoned too and is closed the same
-way — two crashes in a row leave two open runs, and both are closed, not only
-the newest. Open means `active` or `draining`.
-
-A version of `unknown` on either side is never a version change, so a dev build
-after a crashed release reads `abnormal`, not `handoff`. `forced` means the
-process itself acknowledged a kill; `abnormal` means a successor found it dead.
-
-### Downtime is the window nobody answered in
-
-`ReadyFact.downtimeMs` is `readyAt` of the new run minus `unavailableAt` of the
-last run that served — the predecessor's drain plus the successor's boot. A
-110 s forced drain followed by a 4 s boot is 114 s of downtime; the gap between
-the two processes alone would read 4 s before and after that defect was fixed.
-Runs that never became ready answered nobody, so the count passes them: after a
-failed start it still opens where the last serving run stopped answering. It is
-`0` when that run still answers (a handoff whose predecessor has not drained
-yet) and `null` on first boot and when the end was never timed — a crash or a
-hot reload records no `unavailableAt`. `unavailableSince` names the moment it is
-counted from. The gap between two processes is still there, under its own
-name: `StartFact.processGapMs` is the start minus the predecessor's recorded
-stop.
-
-The ledger records what the process says while it can say it. stitchkit never
-calls `process.exit` (ADR 0074), so a stop is recorded on the kernel's `close`
-or `force` path, both awaited. An application that exits the process on its
-own before its shutdown settles loses that last write; the successor then
-finds the run open and closes it as `abnormal`, keeping the `unavailableAt`
-already recorded — which is why the drain moment is written first, at
-`stopAdmission`, and the downtime survives a stop that was never recorded.
-
-The `abnormal` default is a choice, and it is the single-process deployment:
-one process per build, a new pid of the same build means the old one stopped
-answering. Where processes of **one** build overlap on purpose — a cluster, a
-zero-downtime reload of the same build — pass `sameVersionOverlap: 'handoff'`
-to the ledger, and every open run stays open until it records its own
-shutdown. The cost of that setting is symmetric: a real crash under it is
-reported as a handoff and the dead run stays open in the ledger until
-retention drops it.
-
-A version change is the other axis, and its default is the opposite:
-`handoff`, because a release that starts the new build before stopping the
-old one is the common zero-downtime shape. Where builds never overlap — one
-process per deployment (a pm2 fork, a systemd unit, one container), the old
-one stopped before the new one starts — pass `versionChangeOverlap:
-'abnormal'`. An open predecessor of another build then died without
-recording its exit, most often killed during the release itself: it is closed
-as `abnormal` (or `startup-failed`) at the new start, `downtimeMs` is `null`
-instead of `0`, and `previousVersion` / `versionChanged` still describe the
-release. A predecessor that did record its stop is read as before, and its
-downtime is measured. The two settings compose: `sameVersionOverlap:
-'handoff'` keeps open only the runs of a build allowed to overlap the new one.
-
-The list is kept in the order the transitions wrote it —
-every write goes through one atomic update, so that order is the causal one,
-and a successor whose clock lags its predecessor still finds it at the head;
-`startedAt` is data, not the sort key. Retention (`retain`, default 20) drops
-finished runs first and an open one — a live handoff predecessor — only when
-nothing finished is left. Facts are published through the ledger's own
-subscription and resource value; `ApplicationEventSink` remains the strict
-application-state stream.
-
-`createNotificationOutbox` is the transport-neutral durable delivery side. It
-persists before send, claims an item with an expiring lease, carries one stable
-idempotency key into the transport, retries under an injected clock and records
-terminal drops. The guarantee is at-least-once: a crash after remote acceptance
-but before the receipt is persisted may redeliver, so transports should use the
-key when they support deduplication. The retry budget is sized for the outage
-an owner notification has to outlive, not for a flaky call: the default backoff
-doubles from one second and caps at sixty (`backoffDelay`, the one formula the
-client's resumable streams also use, with jitter 0), and the 99 waits between
-the default `maxAttempts` of 100 sum to 1+2+4+8+16+32 s plus 93 × 60 s — about
-94 minutes — before `onDropped` sees `attempt-limit`.
-`state()` is a read and never fails on the bounds a transition enforces — a file
-that grew past `maxStateBytes` under an older limit is inspectable and is
-trimmed by the next transition. Two bounds do fail loudly: `enqueue` past
-`maxQueue` throws rather than dropping silently, and a `backoffMs` that returns
-`NaN`, a negative or an infinite delay rejects the flush. `stop()` lets the
-send in flight finish and claims nothing more; a `send` without its own
-deadline holds `stop()` — and so the resource's `force()` — for that one call,
-so give the transport a timeout. Superseding a key that is being sent right now
-does not recall it: the send completes, and only its receipt is not written.
-
-`createDirectoryInbox` is the receiving side for another program on the same
-host: it drops entries — a release transition, say — into a directory, and
-the application takes each one at least once. It is a managed resource of its
-own (`createDirectoryInbox({ id, directory, schema, handle })`, imported from
-`stitchkit/application/directory-inbox` because it touches files; its types
-and schemas are in `stitchkit/application`) and publishes a handle with
-`flush()` and `state()`. The producer writes each entry
-atomically as `<name>.json` — a temporary name, then a rename; names that start
-with a dot are never read. Entries are delivered in name order, and only after
-`activate`: none reaches the application before it is ready. `stopAdmission`
-stops taking new ones, `drain` waits for the one in flight, and `force` aborts
-the `signal` its handler was given.
-
-Taken and done are separate durable records. Before `handle` runs, the entry
-is claimed with a lease (`leaseMs`, default five minutes); after it returns,
-a receipt replaces the claim and only then is the file removed. A process that
-died mid-delivery leaves a claim, and the entry is taken again once the lease
-runs out — at least once, not exactly once, so a handler that sends somewhere
-should carry the entry's `key` as its idempotency key. A process that died
-after the receipt leaves only the file, which the next pass removes without
-delivering it again. A handler that throws is retried after a backoff from one
-second doubling to five minutes; an entry that fails `schema`, is over
-`maxEntryBytes` or was taken `maxAttempts` times (default 20 — the count
-survives restarts, so an entry whose handling kills the process is not taken
-forever) is moved to `rejected/` with its reason and reported to `onRejected`,
-and the entries after it keep flowing. The state lives in
-`<directory>/.inbox-state.json` under `createFileStateStore`'s inter-process
-lock unless a `store` is supplied.
-
-These primitives depend on the structural `StateStore`. On a server,
-`createFileStateStore` supplies the shared Zod-validated JSON adapter with an
-inter-process lock, unique temporary file, fsync and atomic rename. The lock
-is a file with a heartbeat: the holder refreshes its mtime every third of
-`staleLockMs` (default 3 s), a contender waits up to `lockTimeoutMs` (default
-10 s), and the stale bound must sit inside the timeout — otherwise a crashed
-holder blocks every update until the lock ages out, which the constructor
-refuses. A lock whose heartbeat is stale is reclaimed once its recorded pid is
-gone; a live or unverifiable pid (a reused number, another user's process)
-keeps it for ten stale bounds — and never fewer than thirty missed heartbeats,
-so a scheduler stall on a loaded host cannot pull a live lock from under its
-holder — after which the heartbeat wins and the lock is abandoned. Temporary files a crashed writer left beside the state are swept on
-the store's first update. Ledger corruption may be declared reconstructable;
-an outbox must fail closed rather than silently discard pending delivery.

package/llms/stitchkit.txt

@@ -79,12 +79,12 @@ own, recorded as an ADR.
 | `stitchkit/geo` | server (Bun or Node) | evolving | managed GeoIP reader generations, last-known-good reload and the optional MaxMind adapter |
 | `stitchkit/oauth` | browser **and** server | evolving | provider-neutral Authorization Code + PKCE request and one-shot callback transaction mechanics |
 | `stitchkit/google` | server (Bun or Node) | evolving | optional Google code exchange and verified OIDC identity adapter |
-| `stitchkit/observability` | server | stable<br>_redefined in 2 of the 46 minors since 0.56.2, most recently 0.92.0_ | request/tool event projections — `createObservability`, trace context, sanitisation |
+| `stitchkit/observability` | server | stable<br>_redefined in 2 of the 48 minors since 0.56.2, most recently 0.92.0_ | request/tool event projections — `createObservability`, trace context, sanitisation |
 | `stitchkit/testing` | tests on Bun or Node | stable | in-process generated clients over a real Fetch handler, plus the managed-resource conformance kit |
 | `stitchkit/declaration` | browser + build and deployment tooling (Bun or Node) | evolving | `ProjectDeclarationSchema` — the one machine-readable statement a repository makes about itself |
 | `stitchkit/react` | browser + server rendering | stable | `createCursorQuery`, `createCacheBridge`, QueryClient and `ApiError` retry policy |
 | `stitchkit/react/keyboard` | browser | evolving | which part of a screen gets a key — ordered layers, one Escape per level, list zones with real focus; see [keyboard guide](keyboard.md) |
-| `stitchkit/agent-runtime` | server | evolving<br>_redefined in 22 of the 46 minors since 0.56.2, most recently 0.97.0_ | optional durable conversation/run loop, history, models, prompts, fencing and events |
+| `stitchkit/agent-runtime` | server | evolving<br>_redefined in 22 of the 48 minors since 0.56.2, most recently 0.97.0_ | optional durable conversation/run loop, history, models, prompts, fencing and events |
 | `stitchkit/agent-runtime/sandbox` | server | evolving | optional Linux Bubblewrap sessions, durable workspaces and a host HTTP credential gateway; see [sandbox guide](sandbox.md) |
 | `stitchkit/agent-runtime/testing` | tests on Bun or Node | evolving | credential-free replay, scripted provider faults, deterministic race controls and the agent-store conformance kit |
 | `stitchkit/agent-runtime/harness` | server | evolving | resource-aware process-local facade over the canonical Agent runtime; supervision stays outside |
@@ -94,11 +94,11 @@ own, recorded as an ADR.
 | `stitchkit/agent-runtime/sqlite/bun` | server (Bun) | evolving | durable built-in SQLite store for the agent runtime |
 | `stitchkit/agent-runtime/sqlite/node` | server (Node ≥ 22.5) | evolving | durable built-in SQLite store for the agent runtime |
 | `stitchkit-tui` | terminal (Bun) | evolving | optional official OpenTUI host over a caller-composed headless runtime |
-| `stitchkit/application` | browser + server | evolving<br>_redefined in 10 of the 46 minors since 0.56.2, most recently 0.100.0_ | managed resource graph, readiness, admission, schedules, subtree restart and bounded shutdown |
+| `stitchkit/application` | browser + server | evolving<br>_redefined in 11 of the 48 minors since 0.56.2, most recently 0.103.0_ | managed resource graph, readiness, admission, schedules, subtree restart and bounded shutdown |
 | `stitchkit/application/grammy` | server | evolving | a grammY bot as application resources — configuration, then polling with updates admitted by batch — and the webhook adapter |
 | `stitchkit/application/opentelemetry` | server | evolving | maps application snapshots onto an injected OpenTelemetry `Meter` |
 | `stitchkit/application/schemas` | browser + server | evolving | the application's snapshot, health and shutdown schemas alone, without the kernel |
-| `stitchkit/application/diagnostic-journal` | server | evolving | the local diagnostic journal — the one part of the kernel that spawns, locks and writes files |
+| `stitchkit/application/diagnostic-journal` | server | evolving | the local diagnostic journal — an exclusive bounded writer and snapshot reader with explicit anomalies |
 | `stitchkit/application/directory-inbox` | server | evolving | the directory inbox — entries another program drops into a directory, delivered to the application at least once |
 
 Rule of thumb: browser code imports `stitchkit` and `stitchkit/react`; server

package/llms/tools.2.txt

@@ -365,6 +365,15 @@ multimodal content beside structured per-item `errors`, and charges every item
 to one total 20 MB batch budget. Its MCP and Agent presenters are built in;
 remote fetch cancellation follows the active call signal.
 
+`paths` is one path/URL string or an actual array of strings (at most 20).
+Pass `{ paths: ['image.png'] }`, not `{ paths: '["image.png"]' }`: a JSON
+array written as text fails input validation before any file or network access,
+with the hint `paths is a list written as text — pass an array of paths or one
+path`. The same rule applies to array items and the raw `mountViewFile` input.
+Ordinary file names containing brackets, such as `[preview].png`, remain valid.
+A local file with an unsupported extension is refused before reading; its
+per-item error identifies the caller's path and the extension it saw.
+
 The older `mountWait`, `mountDownload`, `mountUpload` and `mountViewFile`
 functions remain
 intentional raw MCP adapters with their text-envelope behavior. Use them under

package/llms/tools.3.txt

@@ -113,7 +113,7 @@ payload.
 | `ToolCallContext` | _type_ | the context every tool hook receives — `{ source, mcp? }` plus whatever the mount's `context` added |
 | `ViewFileOptions` | _type_ | shared URL/managed-file-boundary policy for `defineViewFileTool`, `mountViewFile` and `resolveMedia` |
 | `ViewFileOutput` | _type_ | neutral managed batch result with multimodal `content` and per-item `errors` |
-| `ViewFileInputSchema` | constant | fixed one-or-many media path/URL input schema |
+| `ViewFileInputSchema` | constant | one media path/URL or an array of at most 20; rejects a JSON array written as text, including in array items, before IO |
 | `ViewFileOutputSchema` | constant | Zod schema for the neutral managed view-file batch result |
 | `ViewFileErrorSchema` | constant | Zod schema for one structured per-item view failure |
 | `McpAnnotations` | _type_ | MCP annotations on a media result |