stitchkit 0.66.1 → 0.68.0

package/llms-full.txt

@@ -58,9 +58,9 @@ own, recorded as an ADR.
 | `stitchkit/testing` | tests on Bun or Node | stable | in-process generated clients over a real Fetch handler, plus the store and managed-resource conformance kits |
 | `stitchkit/declaration` | build and deployment tooling (Bun or Node) | evolving | `ProjectDeclarationSchema` — the one machine-readable statement a repository makes about itself |
 | `stitchkit/react` | browser | stable | `createCursorQuery`, `createCacheBridge` |
-| `stitchkit/agent-runtime` | server | evolving<br>_redefined in 9 of the 11 minors since 0.56.2, most recently 0.66.0_ | optional durable conversation/run loop, history, models, prompts, fencing and events |
+| `stitchkit/agent-runtime` | server | evolving<br>_redefined in 9 of the 13 minors since 0.56.2, most recently 0.66.0_ | optional durable conversation/run loop, history, models, prompts, fencing and events |
 | `stitchkit/agent-runtime/openrouter` | server | evolving | isolated OpenRouter language-model adapter |
-| `stitchkit/application` | server | evolving | managed resource graph, readiness, admission, schedules and bounded shutdown |
+| `stitchkit/application` | server | evolving<br>_redefined in 3 of the 13 minors since 0.56.2, most recently 0.67.0_ | managed resource graph, readiness, admission, schedules and bounded shutdown |
 | `stitchkit/application/grammy` | server | evolving | isolated grammY polling and webhook lifecycle adapters |
 | `stitchkit/application/opentelemetry` | server | evolving | maps application snapshots onto an injected OpenTelemetry `Meter` |
 
@@ -1521,6 +1521,57 @@ focused helper — not a sub-framework.
 | `createCache()` + `cacheHeaders()` | in-memory TTL cache; `Cache-Control` builder |
 | `createEventBus<EventMap>()` | typed in-process pub/sub |
 
+### Contract-first streams
+
+Use an endpoint `stream` descriptor when the item schema and completion belong
+to the contract, rather than handing an application-owned `Response` to
+`rawResponse`:
+
+```ts
+const Item = z.discriminatedUnion('kind', [
+  z.object({ kind: z.literal('line'), text: z.string() }),
+  z.object({ kind: z.literal('complete'), count: z.number().int() }),
+])
+
+const reports = defineContract({ prefix: 'reports' }, {
+  watch: {
+    method: 'GET', path: '/:id/watch', desc: 'Watch one report',
+    params: z.object({ id: z.string() }),
+    stream: {
+      item: Item,
+      format: 'ndjson',
+      maxFrameBytes: 64 * 1024,
+      terminal: z.object({ kind: z.literal('complete') }).loose(),
+    },
+  },
+})
+
+const service = implement(reports, {
+  watch: async function* ({ params, signal }) {
+    yield { kind: 'line', text: `starting ${params.id}` }
+    if (signal.aborted) return
+    yield { kind: 'complete', count: 1 }
+  },
+})
+```
+
+The handler return is inferred as `AsyncIterable<z.output<typeof Item>>`; an
+invalid JavaScript producer is rejected before its value reaches the wire. Data,
+safe errors and normal end use a framework envelope. The default encoded frame
+limit is 256 KiB. `format` defaults to `ndjson`; `heartbeatMs` defaults to five
+seconds; `idleTimeoutSeconds` defaults to disabled; `lifetimeMs` is optional.
+
+After headers, HTTP status can no longer report failure, so the stream sends a
+normalized code and never the raw internal exception. Normal producer completion
+sends an explicit `end`; when `terminal` is declared, at least one item must
+match it. Request abort and client iterator return abort `signal`, including a
+source waiting in `next()` or suspended at a yielded item.
+
+Contract streams are HTTP-only and cannot declare `output`, `rawResponse`,
+multipart or tool exposure. They do not provide replay, cursors or durable
+subscriptions. Keep using `streamingRoute` for an application-owned protocol and
+`rawResponse` for arbitrary response bodies. → ADR 0117.
+
 ### SSE streaming
 
 `streamSSE` returns a `Response`, so its endpoint declares
@@ -1834,23 +1885,46 @@ your own `(pathname) => boolean`.
 
 ### Unix domain sockets
 
-The same typed client dials a local daemon's socket file
-([server side](server.md#local-daemon-over-a-unix-socket)):
+The same typed client dials a local daemon's socket file through an explicit,
+owned Bun/Node transport ([server side](server.md#local-daemon-over-a-unix-socket)):
 
 ```ts
+import { createHttpClient } from 'stitchkit'
+import { createUnixClientTransport } from 'stitchkit/server' // or stitchkit/node
+
+const transport = createUnixClientTransport({
+  socketPath: '/run/my-daemon.sock',
+  maxRequestBytes: 4 * 1024 * 1024,
+  maxResponseBytes: 16 * 1024 * 1024,
+})
 const http = createHttpClient({
-  baseUrl: 'http://localhost', // required prefix source; its host is ignored
-  unix: '/run/my-daemon.sock',
+  baseUrl: 'http://my-daemon', // URL/Host source; never dialled as TCP
+  fetch: transport.fetch,
+  retry: { limit: 0 },
 })
 const daemon = createClient(daemonContract, http)
+
+// At application shutdown:
+await transport.close()
 ```
 
-`baseUrl` stays required — it supplies the path prefix and the `Host` header,
-while the connection itself goes through the socket file. Bun runtime only:
-other runtimes ignore the option and dial `baseUrl` over TCP (Node's fetch
-would need an undici dispatcher — out of scope). A missing socket file
-surfaces as a normal `ApiError` and is not retried (transport retry stays
-connection-refused-only).
+`baseUrl` stays required because it supplies the URL and `Host` header. The
+adapter structurally owns dispatch: relative and absolute redirects use the same
+socket, and a missing socket cannot fall through to that host over TCP. Defaults
+are 16 MiB request/response bodies, 64 KiB headers, 30 s to response headers,
+eight connections and five redirects.
+
+`UnixClientTransportError` carries a stable `code` and `delivery`:
+`not-dispatched`, `possibly-dispatched` or `response-received`. Only the first
+proves that the remote operation did not begin; Stitchkit never silently retries
+an ambiguous write. Response consumption/cancellation belongs to the operation,
+and `close()` interrupts active work and destroys owned connections.
+
+The legacy `createHttpClient({ unix: '/absolute/path' })` spelling remains a
+Bun-only convenience. On a non-Bun runtime it now refuses before dispatch
+instead of ignoring the selection and dialing TCP. `unix` and an injected
+`fetch` are mutually exclusive; use `createUnixClientTransport` for portable,
+explicit lifecycle ownership. → ADR 0116.
 
 `trace: true` mints a fresh root trace per request. The stitchkit server
 [continues an inbound `traceparent`](./observability.md#trace-context), so the
@@ -2218,6 +2292,41 @@ sends one. The result keeps the full `react-query-kit` surface (`.getKey()`,
 `useSuspenseInfiniteQuery`, every option). The endpoint must return the
 `{ items, nextCursor }` envelope — see [Contracts → pagination](./contracts.md#pagination).
 
+## Contract-first streams
+
+When an endpoint declares `stream`, `createClient` returns a schema-derived
+owned iterator rather than an untyped `Response`:
+
+```ts
+const Progress = z.discriminatedUnion('kind', [
+  z.object({ kind: z.literal('line'), text: z.string() }),
+  z.object({ kind: z.literal('complete'), count: z.number().int() }),
+])
+
+const contract = defineContract({ prefix: 'reports' }, {
+  watch: {
+    method: 'GET', path: '/:id/watch', desc: 'Watch one report',
+    params: z.object({ id: z.string() }),
+    stream: {
+      item: Progress,
+      format: 'ndjson',                 // default; `sse` is also supported
+      maxFrameBytes: 64 * 1024,         // default 256 KiB
+      terminal: z.object({ kind: z.literal('complete') }).loose(),
+    },
+  },
+})
+
+const stream = await createClient(contract, http).watch({ id: 'r-1' })
+for await (const item of stream) console.log(item) // inferred from Progress
+```
+
+The iterator validates every frame and item. Normal completion requires the
+wire `end` frame and, when declared, at least one matching terminal item; EOF is
+`STREAM_TRUNCATED`, and a missing terminal is `STREAM_TERMINAL_MISSING`.
+`return()`/`break`, caller abort, producer failure and optional `lifetimeMs`
+converge on the request operation. See the
+[server half](./server.md#contract-first-streams). → ADR 0117.
+
 ## SSE
 
 For a streaming endpoint, consume the response with `parseSSE`:
@@ -2233,7 +2342,9 @@ for await (const event of parseSSE(res)) {
 
 The server side is [`streamSSE`](./server.md#sse-streaming), or
 [`sseRoute`](./server.md#long-lived-subscriptions) for a subscription that stays
-open.
+open. One line is bounded by `maxLineBytes` (default 1 MiB), UTF-8 is decoded
+strictly and malformed input throws. Supply `onParseError` only when
+skip-and-report is an explicit application policy.
 
 ## NDJSON
 
@@ -2265,8 +2376,9 @@ convenience: a long-lived stream must send something while it is idle or
 intermediaries drop it, and an empty line is the natural pulse for this framing.
 Writing the rule down on both sides is what stops it being a verbal agreement —
 the server's keep-alive and the reader's skip are one decision with two
-implementations. A frame that is not valid JSON goes to `onParseError` rather
-than throwing, so one bad line does not end the subscription.
+implementations. One line is bounded by `maxLineBytes` (default 1 MiB), UTF-8 is
+decoded strictly and malformed input throws. Passing `onParseError` explicitly
+selects tolerant skip-and-report behaviour.
 
 
 ==============================================================================
@@ -4243,17 +4355,24 @@ const cleanup = createManagedSchedule({
   run: ({ signal }) => removeExpiredRecords(signal),
 })
 
+const http = managedServerResource({
+  id: 'http',
+  dependsOn: [database],
+  // Called during `start`, after `database` is ready — which is how "bind the
+  // port once the database is up" is expressed. Pass an already-running server
+  // instead when the application created it itself.
+  server: () => createServer({ port: env.PORT, services }),
+})
+
 const app = createApplication({
   id: 'service',
-  resources: [
-    database,
-    managedServerResource({ id: 'http', server, dependsOn: ['database'] }),
-    cleanup,
-  ],
+  resources: [database, http, cleanup],
+  // One number for how long this application may take to stop. `shutdown()`
+  // with no options and the signal path both spend it.
+  shutdown: { gracePeriodMs: 30_000, forceTimeoutMs: 5_000 },
 })
 
 const signals = bindProcessSignals(app, {
-  shutdown: { gracePeriodMs: 30_000, forceTimeoutMs: 5_000 },
   onComplete: (result) => {
     process.exitCode = result.outcome === 'clean' ? 0 : 1
   },
@@ -4263,9 +4382,10 @@ await app.start()
 ```
 
 The exact resource callbacks are typed by their public configuration. The
-important ownership rule is stable: the application creates and configures the
-database/server/provider objects; Stitchkit orders their process-local
-lifecycle.
+important ownership rule is stable: the application decides what the
+database/server/provider objects are and how they are configured; Stitchkit
+orders their process-local lifecycle and decides *when* they come into
+existence.
 
 ## Resource authoring
 
@@ -4304,6 +4424,40 @@ Invoking `start` makes the descriptor rollback-eligible immediately. Its
 before returning a runtime handle. The kernel calls cleanup once and continues
 cleaning other attempted resources even if one close fails.
 
+### Handing a resource to the resources that depend on it
+
+`dependsOn` says *when*. To say *what*, return a `value` from `start` and read
+it with `context.use(...)`:
+
+```ts
+const database = defineManagedResource({
+  id: 'database',
+  start: async ({ signal }) => ({ value: await connect(env.DATABASE_URL, signal) }),
+})
+
+const worker = defineManagedResource({
+  id: 'worker',
+  dependsOn: [database],
+  start: (context) => {
+    const db = context.use(database)   // Connection — not Connection | null
+    return { completion: consume(db, context.signal) }
+  },
+})
+```
+
+Declare the dependency with the **resource**, not its id, whenever you intend to
+read from it: that is the form `use` can type, and it keeps the declaration and
+the read from drifting apart. A string still works when all you need is order.
+
+The value is published when `start` resolves and stays readable for the rest of
+the application's life — from `activate` and from the shutdown phases too, where
+a dependant may still need the handle it was given.
+
+`use` refuses two things, both loudly: a resource that was never declared in
+`dependsOn` (it happens to work whenever declaration order is lucky), and a
+resource that published nothing. The second is refused by the compiler as well —
+reading a value off a resource with no `value` in its `start` does not type.
+
 ## Readiness and health
 
 `await app.start()` resolves only after every required resource is ready and
@@ -4488,6 +4642,69 @@ try {
 `release()` is idempotent. Admission and counter increment are atomic, so work
 cannot slip between the shutdown check and drain accounting.
 
+### Bounded operation admission
+
+Compose `createBoundedAdmission` when accepted work also competes for a finite
+process-local resource:
+
+```ts
+const generations = createBoundedAdmission({
+  upstream: app.admission,
+  policy: {
+    global: { maxConcurrent: 8, rate: { limit: 120, intervalMs: 60_000 } },
+    perKey: { maxConcurrent: 1, maxKeys: 2_000 },
+  },
+})
+
+await generations.run(accountId, ({ signal }) => generate({ signal }), {
+  signal: request.signal,
+  timeoutMs: 30_000,
+})
+```
+
+Acquisition is no-queue and atomic across every configured budget. Refusal names
+the exact bound; only a rate refusal carries `retryAfterMs`. `maxKeys` keeps the
+per-key registry finite, and expired idle entries are retired.
+
+The caller timeout is a wait budget, not proof that the resource stopped. It
+aborts the signal and settles the caller, but the lease remains active until the
+underlying Promise actually settles. `drain()` therefore reports real work;
+`force()` closes admission and reports remaining work without claiming to have
+terminated it. → ADR 0118.
+
+### Bounded delivery and byte credit
+
+`createBoundedChannel` is for one asynchronous reader when an event bus is not a
+queue:
+
+```ts
+const output = createBoundedChannel<string>({
+  policy: 'ordered',
+  maxItems: 64,
+  maxBytes: 256 * 1024,
+  sizeOf: (value) => new TextEncoder().encode(value).byteLength,
+})
+
+const progress = createBoundedChannel<{ revision: number }>({
+  policy: 'latest',
+  maxItems: 1,
+  maxBytes: 128,
+  sizeOf: () => 128,
+})
+```
+
+`ordered` never overwrites accepted values; overflow is a reasoned refusal.
+`latest` retains exactly one pending replaceable value and reports
+`coalesced`. Offers never create a hidden writer queue, and only one `next()` may
+wait. Close chooses `drain` (default) or `discard`; abort discards; failure
+rejects the parked and all later reads.
+
+`createCreditWindow({ capacityBytes })` is the smaller primitive for a protocol
+that already owns its queue but needs exact byte permission. Each credit lease
+replenishes once; it is flow-control credit, not a durable acknowledgement. The
+application snapshot sink now shares the same latest-value mechanics without
+changing its revision or status contract. → ADR 0119.
+
 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
@@ -4498,6 +4715,15 @@ Do not add a second `process.on('SIGTERM')` handler around the application.
 `bindProcessSignals(app)` is the force/escalation owner. Exit code and hard-exit
 policy remain application/supervisor choices.
 
+**Where the budget comes from on the signal path.** `bindProcessSignals(app)`
+with no `shutdown` forwards nothing, so the application spends the budget it
+declared in `createApplication({ shutdown })`. Pass `shutdown` to the binding
+only to override that budget for signals specifically; passing one key overrides
+that key alone and leaves the other at the declaration. Declare the budget once,
+on the application — repeating it in both places is how the two numbers start to
+disagree, and the operator's supervisor timeout is calculated from the one they
+can read.
+
 ## Managed schedules
 
 Schedules activate only after top-level readiness:
@@ -4753,6 +4979,115 @@ 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: () => createServer({ port: env.PORT, services }),
+})
+
+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.
+
+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:
@@ -7928,6 +8263,186 @@ implement `AgentRuntimeStoreDriver` and compose the aggregate with
    runtime): bootstrap the server, one HTTP request, and any feature you rely on
    (Socket.IO connect, an MCP tool call, a multipart upload, …).
 
+## Released migration: 0.68.0
+
+### Make Unix transport selection explicit outside Bun
+
+The legacy `unix` option remains a Bun convenience, but on Node or another
+runtime it now fails before dispatch. Replace it with the owned adapter and close
+that adapter with the application:
+
+```ts
+// before — unsafe outside Bun: an unsupported fetch could dial baseUrl over TCP
+const http = createHttpClient({ baseUrl, unix: '/run/service.sock' })
+
+// after — Bun and Node; every dispatch and redirect stays on the socket
+import { createUnixClientTransport } from 'stitchkit/server' // or stitchkit/node
+const transport = createUnixClientTransport({ socketPath: '/run/service.sock' })
+const http = createHttpClient({ baseUrl, fetch: transport.fetch })
+// during shutdown
+await transport.close()
+```
+
+Do not automatically replay `possibly-dispatched`: a timeout or connection loss
+after bytes left the process does not prove that a write did not happen.
+
+### Choose tolerant stream parsing explicitly
+
+`parseNDJSON` and `parseSSE` now throw on malformed JSON, invalid UTF-8 and an
+over-limit line. The default line ceiling is 1 MiB. If a feed deliberately skips
+bad records, retain that policy explicitly:
+
+```ts
+// before — malformed input disappeared implicitly
+parseNDJSON(response)
+
+// after — ordinary fail-closed path
+parseNDJSON(response, { maxLineBytes: 256 * 1024 })
+
+// after — deliberately tolerant path
+parseNDJSON(response, { onParseError: (raw, error) => report(raw, error) })
+```
+
+### Extend exhaustive framework-error handling
+
+If a switch makes `StitchErrorCode` exhaustive, add
+`STREAM_ITEM_INVALID`, `STREAM_FRAME_TOO_LARGE`,
+`STREAM_TERMINAL_MISSING` and `STREAM_LIFETIME_EXCEEDED`. A partial application
+status map needs no change (ADR 0105).
+
+The admission/channel APIs and endpoint `stream` descriptor are additive; raw
+responses and raw `streamingRoute` remain supported.
+
+## Released migration: 0.67.0
+
+Three application-kernel changes. Two of them fix silent failures, so the most
+important part of this migration is not what the compiler points at — it is the
+two things that change with no compile error at all: **when your server is
+created**, and **which shutdown budget a signal spends**.
+
+### If you gave `managedServerResource` a thunk
+
+It is now called during `start`, after the resource's dependencies are ready —
+the reading the type always suggested. Before, it was called on the way *down*,
+so `app.start()` resolved, the snapshot said `healthy` and `ready`, and nothing
+was bound to the port.
+
+If your application looked like this, it was never listening:
+
+```ts
+// before — resolves clean, listens on nothing
+managedServerResource({ id: 'http', dependsOn: ['database'], server: () => createServer(config) })
+```
+
+Nothing to change: the same code now binds the port. Check your startup logs for
+a healthy report you never actually verified with a request.
+
+If you used the spread workaround — this resource's phases over your own
+`start` — it keeps working, and you can now delete it:
+
+```ts
+// before
+let handle: ManagedServerHandle<T> | null = null
+const shutdown = managedServerResource({ id: 'http', server: () => handle! })
+const http = defineManagedResource({
+  ...shutdown,
+  dependsOn: ['database', 'socket-io'],
+  start: () => { handle = createServer(config) },
+})
+
+// after
+const http = managedServerResource({
+  id: 'http',
+  dependsOn: [database, socketIo],
+  server: () => createServer(config),
+})
+```
+
+An already-created handle is adopted exactly as before.
+
+### If you passed `shutdown` to `bindProcessSignals`
+
+`bindProcessSignals` used to fill in the schema's defaults for every budget you
+omitted, which made `createApplication({ shutdown })` unreachable on the signal
+path — the one path production stops through. An application declaring five
+seconds took thirty-five.
+
+Declare the budget once, on the application, and delete the repetition:
+
+```ts
+// before — the same two numbers in two places, and only one of them applied
+const app = createApplication({ id: 'svc', resources, shutdown: SHUTDOWN_BUDGET })
+bindProcessSignals(app, { shutdown: SHUTDOWN_BUDGET })
+
+// after
+const app = createApplication({ id: 'svc', resources, shutdown: SHUTDOWN_BUDGET })
+bindProcessSignals(app)
+```
+
+**Check this even if you change nothing.** If you declared a budget on the
+application and did not repeat it on the binding, your process has been stopping
+on 30 s / 5 s and will now stop on what you declared. Compare it against the
+supervisor timeout that watches it — `kill_timeout`, `TimeoutStopSec` — because
+that number was probably calculated from the declaration.
+
+Passing `shutdown` to the binding still works and still wins, key by key: one
+key overrides that key alone and leaves the other at the declaration.
+
+### If you read `resource.dependsOn`
+
+Its type widened from `readonly string[]` to `readonly ManagedResourceDependency[]`
+— `string | ManagedResource` — so a dependency can be declared as the resource
+itself. Declaring stays compatible; reading needs one call:
+
+```ts
+// before
+const ids: readonly string[] = resource.dependsOn ?? []
+
+// after
+import { managedResourceDependencyId } from 'stitchkit/application'
+const ids = (resource.dependsOn ?? []).map(managedResourceDependencyId)
+```
+
+### If you thread a handle through a module-local
+
+This is the pattern the change exists to remove, and it is opt-in — nothing
+breaks if you keep yours:
+
+```ts
+// before
+let socket: SocketHandle | null = null
+const socketIo = defineManagedResource({
+  id: 'socket-io',
+  start: async () => { socket = await createSocketServer(config) },
+})
+const http = defineManagedResource({
+  id: 'http',
+  dependsOn: ['socket-io'],
+  start: () => {
+    if (!socket) throw new Error('socket is not initialized')   // unreachable
+    server = createServer({ socket })
+  },
+})
+
+// after
+const socketIo = defineManagedResource({
+  id: 'socket-io',
+  start: async () => ({ value: await createSocketServer(config) }),
+})
+const http = defineManagedResource({
+  id: 'http',
+  dependsOn: [socketIo],
+  start: (context) => {
+    server = createServer({ socket: context.use(socketIo) })   // SocketHandle
+  },
+})
+```
+
+Declare the dependency with the **resource** when you intend to read from it —
+that is the form `use` can type. `use` refuses a resource missing from
+`dependsOn`, and refuses one that published no value; the second refusal is a
+compile error too.
+
 ## Released migration: 0.66.0
 
 Three changes, and only one of them is a feature. The other two are shapes that
@@ -10191,7 +10706,7 @@ The browser-and-server entrypoint. Re-exports everything from
 | `createUrlBuilders` | function | build one exact URL builder per contract in a registry |
 | `UrlBuilderConfig` | _type_ | explicit `{ baseUrl }` source for a URL builder |
 | `ClientConfig` | _type_ | config for `createClient`'s bare-fetch mode (2nd arg, no `HttpClient`) |
-| `ClientFetch` | _type_ | injectable Fetch-compatible transport used by framework testing adapters |
+| `ClientFetch` | _type_ | injectable Fetch-compatible transport used by framework and application-owned adapters |
 | `ClientRequestOptions` | _type_ | per-call `{ signal?: AbortSignal }` passed through an endpoint callable's `.withOptions(...)`; caller abort is distinct from timeout — [guide](../guide/client.md#per-call-cancellation) |
 | `ContractClientConfig` | _type_ | per-tenant / resource-scoped client config — dynamic `pathPrefix` + `stripPrefixKeys` ([guide](../guide/client.md#contractclientconfig--per-tenant--resource-scoped-clients)) |
 | `contractEndpointMatchers` | function | compile exact pathname matchers for selected HTTP contract operations and expected-401 policy |
@@ -10200,7 +10715,7 @@ The browser-and-server entrypoint. Re-exports everything from
 | `ApiError` | class | a non-2xx response, with `code` / `status` / `details` / `hint` and optional readonly `traceId` from `x-request-id` |
 | `HttpClient` | _type_ | the transport interface `createClient` builds on |
 | `ConfiguredHttpClient` | _type_ | a framework-created `HttpClient` carrying its readonly `baseUrl` for URL builders |
-| `HttpClientConfig` | _type_ | config for `createHttpClient`; retry `limit` counts retries after the initial attempt (default 2 = at most 3 GET attempts), with `statusCodes: []` by default; `unix` dials a unix domain socket (Bun only) — [details](../guide/client.md#createhttpclient) |
+| `HttpClientConfig` | _type_ | config for `createHttpClient`; retry `limit` counts retries after the initial attempt (default 2 = at most 3 GET attempts), with `statusCodes: []` by default; `fetch` installs an explicit transport and is mutually exclusive with the legacy Bun-only `unix` option — [details](../guide/client.md#createhttpclient) |
 | `UnauthorizedMatcher` | _type_ | exact `(pathname) => boolean` policy accepted by `suppressUnauthorizedFor` |
 | `RequestOptions` | _type_ | per-call options — params, timeout, response type |
 | `HeaderProvider` | _type_ | static or per-request headers |
@@ -10218,6 +10733,8 @@ The browser-and-server entrypoint. Re-exports everything from
 | `createRetainedTopics` | function | retained last-value store for sticky events — [guide](../guide/realtime.md#sticky-events) |
 | `parseSSE` | function | parse an SSE `Response` into an async generator — [guide](../guide/client.md#sse) |
 | `parseNDJSON` | function | parse an NDJSON `Response`; blank keep-alive lines are skipped — [guide](../guide/client.md#ndjson) |
+| `ContractStreamFrameSchema` / `ContractStreamFrame` | schema / _type_ | internal-on-the-wire `data` / safe `error` / `end` envelope of a contract-first stream |
+| `DEFAULT_CONTRACT_STREAM_FRAME_BYTES` | const | default maximum encoded contract-stream frame: 256 KiB |
 | `SocketIOClient` | _type_ | low-level client handle; `emit` reports disconnected drops and `emitWithAck` exposes the native Promise primitive used by validated `request()` |
 | `SocketIOClientPeerLoaders` | _type_ | inject `socket.io-client` so a bundler can put it in a self-contained artifact |
 | `SocketIOClientConfig` | _type_ | config for `createSocketIOClient` (incl. `retain`, `onConnectError`, `onDroppedEmit`) |
@@ -10293,6 +10810,7 @@ from the root `stitchkit`.
 | `ContractDef` | _type_ | a defined contract |
 | `ContractMeta` | _type_ | a contract's `prefix` + optional `scope` and `meta` (a default every endpoint shallow-merges over) |
 | `EndpointDef` | _type_ | a single endpoint definition; `output` declares JSON response presence (`null` is data, `undefined` is invalid) |
+| `EndpointStreamDescriptor` | _type_ | HTTP-only schema-derived stream declaration: item schema, NDJSON/SSE framing, frame/lifetime/heartbeat/idle bounds and optional terminal predicate — [guide](../guide/server.md#contract-first-streams) |
 | `HeadEndpointDef` | _type_ | explicit HTTP-only, bodyless `HEAD` endpoint definition |
 | `EndpointResponseMeta` | _type_ | static success metadata declared by an HTTP-only typed-data endpoint |
 | `ResponseMetadata` | _type_ | per-request outbound collector exposed as `ctx.response` only for a `responseMeta` endpoint |
@@ -10551,6 +11069,12 @@ Also re-exports the error helpers from `stitchkit/contract`.
 | `StreamingRouteOptions` | _type_ | options for `streamingRoute` / `ndjsonRoute` / `sseRoute` |
 | `StreamingSourceContext` | _type_ | what a streaming source is given, including the cancellation `signal` |
 | `StreamingFormat` | _type_ | `'ndjson' \| 'sse'` |
+| `createUnixClientTransport` | function | owned Fetch-compatible Unix-socket transport on Bun and Node; every redirect stays on the socket — [guide](../guide/client.md#unix-domain-sockets) |
+| `UnixClientTransportConfig` | _type_ | absolute socket path plus request/response/header/connection/redirect bounds |
+| `UnixClientTransport` | _type_ | `{ fetch, closed, close() }`; `close()` settles owned active work |
+| `UnixClientTransportError` | class | stable transport failure with `code` and dispatch certainty in `delivery` |
+| `UnixClientTransportErrorCode` | _type_ | finite Unix transport failure-code union |
+| `UnixClientDeliveryState` | _type_ | `not-dispatched \| possibly-dispatched \| response-received`; input to application retry policy, never an implicit retry |
 
 ### OpenAPI
 
@@ -10584,17 +11108,55 @@ cutovers are covered by the executable
 | `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 | adapt an existing managed server without copying its HTTP/WebSocket shutdown machine |
+| `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 and separate readiness/completion promises |
-| `ManagedServerResourceConfig` | _type_ | existing managed server, stable ID, dependencies and policy for `managedServerResource` |
+| `ManagedResource` / `ManagedResourceContext` / `ManagedResourceStartResult` | _type_ | resource lifecycle callbacks, shared deadlines, health reporting, separate readiness/completion promises and the value a resource publishes to its dependants |
+| `ManagedResourceDependency` | _type_ | a dependency named by id or given as the resource itself — the second form is what `context.use(...)` can type |
+| `ManagedResourcePublished` | _type_ | the value type `context.use(resource)` returns, recovered from that resource's own `start` |
+| `ManagedResourcePublishesNoValue` | _type_ | what `context.use(...)` returns for a resource that publishes nothing — a branded refusal rather than `never`, so reading it does not silently compile |
+| `ManagedServerResourceConfig` | _type_ | the server or a thunk that makes one, stable ID, dependencies and policy for `managedServerResource` |
+| `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` |
+| `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 |
+
+### 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 |
+
 ### Managed schedules
 
 | Export | Kind | Summary |
@@ -11311,6 +11873,7 @@ runtime-agnostic pieces of `stitchkit/server` and the error helpers.
 | `serveNode` | function | build the router and start a Node HTTP server (via `srvx`) |
 | `createHandler` | function | the router as a bare `(req) => Response` (same as `/server`) |
 | `createSocketIOServer` | function | the typed Node Socket.IO server (`io` + `attach`; no Bun engine declarations) |
+| `createUnixClientTransport` | function | the same fail-closed Bun/Node Unix client adapter exported by `stitchkit/server` |
 | `implement` / `createImplement` / `createScopedImplement` / `createScopedImplementRegistry` / `createMultipartStream` | function | bind a contract to typed handlers, optionally typed per endpoint scope (same as `/server`) |
 | `NodeServerConfig` | _type_ | config for `serveNode` |
 | `NodeServerHandle` | _type_ | managed Node handle (`url`, `port`, `runtime`, `status`, `shutdown`) |
@@ -11318,6 +11881,8 @@ runtime-agnostic pieces of `stitchkit/server` and the error helpers.
 | `NodeSocketLifecycle` | _type_ | Bun-free Socket.IO lifecycle accepted by `serveNode` |
 | `HandlerConfig` / `ServiceDef` / `RawRoute` / `RawRouteContext` | _type_ | runtime-neutral handler types; raw routes default their host server to `unknown` |
 | `SocketIORequestPolicy` / `SocketIOServerConfig` / `SocketIOPeerLoaders` / `SocketIOServerHandle` | _type_ | runtime-neutral handshake policy, config, optional-peer loaders and the Bun-free Node handle with `io`, `attach` and lifecycle |
+| `UnixClientTransportConfig` / `UnixClientTransport` | _type_ | Unix socket bounds and owned Fetch-compatible handle |
+| `UnixClientTransportError` / `UnixClientTransportErrorCode` / `UnixClientDeliveryState` | class / _type_ | stable failure plus dispatch certainty; no cross-transport fallback |
 | `AppError` + `appError` / `badRequest` / `unauthorized` / `forbidden` / `notFound` / `conflict` / `rateLimited` | — | error helpers (same as `/contract`) |
 
 ---