stitchkit 0.94.0 → 0.95.0

package/llms/application.2.txt

@@ -4,8 +4,272 @@
 > `llms.txt` in this package.
 
 Parts of this slice:
-- `llms/application.txt`: Guide: Managed application kernel  (docs/guide/application-kernel.md) · Guide: Application migration recipes  (docs/guide/application-migration-recipes.md)
-- `llms/application.2.txt`: API reference: `stitchkit/application`  (docs/api/reference.md)
+- `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)
@@ -26,11 +290,11 @@ cutovers are covered by the executable
 | `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 |
+| `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` | _type_ | pure transition inputs (`TransitionRunInput` for ready and draining, extended with `forced` for shutdown), the same-build overlap policy (`abnormal` default / `handoff`) 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 |

package/llms/application.txt

@@ -5,8 +5,8 @@
 > Continues in `llms/application.2.txt`.
 
 Parts of this slice:
-- `llms/application.txt`: Guide: Managed application kernel  (docs/guide/application-kernel.md) · Guide: Application migration recipes  (docs/guide/application-migration-recipes.md)
-- `llms/application.2.txt`: API reference: `stitchkit/application`  (docs/api/reference.md)
+- `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: Managed application kernel  (docs/guide/application-kernel.md)
@@ -208,6 +208,12 @@ answered the question, and the answer stands. (It used to be overwritten — and
 the example above hides that, because `healthy` is the same value that
 overwrote it.)
 
+**Reporting the same health again is not a change.** A resource may confirm its
+health on a timer; a report with the value it already reported publishes
+nothing — no new revision, no `changedAt`, no subscriber call. A change of value
+publishes once, as does the first report that confirms the `healthy` the kernel
+assumed at readiness.
+
 **A resource is required unless you write `required: false`.** That default is
 what makes the next sentence bite.
 
@@ -809,39 +815,74 @@ application-owned.
 ## Durable process facts and owner notifications
 
 `createProcessLifecycleLedger` records a bounded versioned list of process runs.
-Start, readiness and shutdown target both `runId` and `pid`, so hot reload and
-PID reuse cannot close the wrong generation. A start classifies what happened to
-the newest run before it, and the classification is decided by three facts —
-whether that run recorded its own exit, whether the pid is the same, and whether
-the version changed:
+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` / `abnormal` as recorded | unchanged |
-| still `active` | yes | — | `hot-reload` | `hot-reload`, closed at the new start |
-| still `active` | no | changed | `handoff` | stays `active`; it records its own stop later |
-| still `active` | no | same | `abnormal` (default) | `abnormal`, closed at the new start — an upper bound, the crash time is unknown |
+| 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` | stays open; it records its own stop later |
+| 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.
 
-The last row is a choice, and the default is the single-process deployment:
+### 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 two processes of **one** build overlap on purpose — a
-cluster, a zero-downtime reload of the same build — pass
-`sameVersionOverlap: 'handoff'` to the ledger, and the predecessor stays
-`active` 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 `active` in the ledger until retention drops it. 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 active 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.
+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. 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
@@ -878,267 +919,3 @@ 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.
-
-==============================================================================
-# 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.