stitchkit 0.102.0 → 0.103.0

package/llms/application.2.txt

@@ -1,16 +1,171 @@
-# stitchkit/application — stitchkit docs slice, part 2 of 2
+# stitchkit/application — stitchkit docs slice, part 2 of 3
 
 > Generated from the `docs/` tree by `bun run gen:llms`. The index of all slices is
 > `llms.txt` in this package.
+> Continues in `llms/application.3.txt`.
 
 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)  (continued)
 ==============================================================================
 
+## 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.
+
 ## Recovering change subscriptions
 
 `changeSubscriptionResource` is an optional resource over a consumer-owned driver.
@@ -330,268 +485,3 @@ Keep the product code that still owns durable state and 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 — 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 |
-
-`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).
-
-### 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.