stitchkit 0.108.4 → 0.109.0

package/llms/telegram.txt

@@ -337,9 +337,10 @@ import { Database } from 'bun:sqlite'
 import type { Update } from 'grammy/types'
 
 const webhook = { token: env.BOT_TOKEN, url: env.WEBHOOK_URL, secret: env.WEBHOOK_SECRET }
+const updateStore = sqliteTelegramUpdateStore({ database: new Database(env.UPDATES_DB) })
 
 const intake = createTelegramUpdateIntake<Update>({
-  store: sqliteTelegramUpdateStore({ database: new Database(env.UPDATES_DB) }),
+  store: updateStore,
   handle: (update) => bot.handleUpdate(update),
   onFailure: (failure) => logger.warn('Update failed', { ...failure }),
 })
@@ -383,13 +384,55 @@ fix (a refused message, a blocked user) is abandoned; `maxAttempts` (5) ends
 the rest. Delivery is at least once: a handler that finished but could not be
 recorded as finished runs again.
 
+Use `handleAttempt` when the handler needs the immutable attempt fence and an
+ownership-loss signal. A signal asks slow work to stop; the fence is what
+authorizes a domain write. Check it through a transaction-bound reference store
+inside the same database transaction as that write:
+
+```ts
+handleAttempt: async (update, { fence, ownerLost }) => {
+  ownerLost.throwIfAborted()
+  await database.transaction(async (tx) => {
+    const transactionStore = postgresTelegramUpdateStore({
+      query: (text, parameters) => tx.query(text, parameters),
+      createTable: false,
+    })
+    if (!(await transactionStore.owns(fence, Date.now()))) return
+    await applyDomainTransition(tx, update)
+  })
+}
+```
+
+The fence contains the claim's own `{ updateId, attempt, claimId }`. The opaque
+`claimId` is persisted and never reused, so an old handler cannot adopt either
+a newer attempt or a pruned and recreated `updateId`. Existing `handle(update)`
+remains unchanged, including direct functions whose own optional second
+argument has a different meaning.
+
+For a final obligation, configure `handleExhaustion`. The reference store keeps
+the terminal record unacknowledged until this handler resolves, including
+across restart; a throw leaves it for the next sweep. Delivery is at least once,
+so use the complete `{ updateId, attempt, claimId }` as an idempotency key in
+the consumer database:
+
+```ts
+handleExhaustion: ({ updateId, attempt, claimId, update, error }) =>
+  recordFinalFailureOnce({ key: `telegram:${updateId}:${attempt}:${claimId}`, update, error })
+```
+
+This reuses the update row and table. Without `handleExhaustion`, terminal
+abandonment retains its previous behavior.
+
 With grammY the handler is `bot.handleUpdate`, which wraps a middleware's error
 in a `BotError`; the intake unwraps it, so `retry`, `onFailure` and the error
 stored with the update are what the middleware threw — a `retry` that returns
 `false` for the bot's own terminal error sees that error.
 
-The store is an interface of six atomic steps (`TelegramUpdateStore`), so the
-bot's own database holds it:
+The base store remains the six atomic steps of `TelegramUpdateStore`. A
+`TelegramUpdateFencedStore` adds `claimOwned`, `renewOwned`, `owns` and
+`settleOwned`; `TelegramUpdateDurableStore` adds the final-obligation methods.
+Reference stores implement both, so the bot's own database holds the fence and
+final obligation without a second queue:
 
 | Store | Takes |
 |---|---|
@@ -416,7 +459,12 @@ postgresTelegramUpdateStore({
 Each rule is one conditional statement, so a claim is atomic across every
 process sharing the table. By default the table is created on first use; where
 migrations own the schema, `postgresTelegramUpdateStoreSchema(table)` is the
-statement to put in one.
+statement to put in one. Apply it before using `handleAttempt` or
+`handleExhaustion`; it adds `claim_id` idempotently. Legacy `handle(update)`
+uses base PostgreSQL operations that do not reference that column. SQLite adds
+the column automatically and tolerates two rolling processes racing the
+migration. A direct base-store claim with `durableExhaustion: true` also opts
+into the column-backed durable capability.
 
 A store of your own — over an ORM, another database — is put through the same
 rules the shipped ones are, concurrent claims included:
@@ -506,13 +554,16 @@ injected grammY bot. → ADR 0143, ADR 0201 — [guide](../guide/telegram.md)
 | `telegramWebhookUrl` | function | the address with an `owner` tag derived from the secret: equal for one secret, different for another, the path untouched |
 | `checkTelegramWebhook` / `TelegramWebhookState` | function / _type_ | whether the webhook still points here: `owned`, `ownerHost`, `pendingUpdates`, Telegram's `lastError` |
 | `receiveTelegramWebhook` / `ReceiveTelegramWebhookOptions` / `TelegramUpdateAcceptance` | function / _type_ | one webhook `Request`: 403 without the secret (compared in constant time), 405 for another method, 400 for no update, 200 once `accept` recorded it |
-| `createTelegramUpdateIntake` | function | webhook updates recorded before Telegram is answered and handled after: chat order kept, other chats alongside up to `maxConcurrent`, a renewed lease per attempt, a sweep that takes over what a restart or a dead process left, retries, `maxAttempts`, finished updates remembered `retainMs` to refuse repeats; at least once |
-| `TelegramUpdateIntakeConfig` / `TelegramUpdateIntake` / `TelegramUpdateEnvelope` / `TelegramUpdateFailure` / `TelegramUpdateStoreStep` | _type_ | `store`, `handle` (a grammY `BotError` is unwrapped: `retry`, `onFailure` and the stored error see what the middleware threw), `retry`, `maxAttempts` (5), `leaseMs` (120 000), `pendingGraceMs` (60 000), `sweepEveryMs` (30 000), `retainMs` (24 h), `maxConcurrent` (32), `onFailure`, `onStoreError`, `now`; `accept(body)`, `start()`, `sweep()`, `idle()`, `close()` |
-| `TelegramUpdateStore` / `StoredTelegramUpdate` / `TelegramUpdateState` / `TelegramUpdateSettlement` / `TelegramUpdateClaimOptions` / `TelegramUpdateDueQuery` | _type_ | the store an intake runs on: `add`, `claim`, `renew`, `settle`, `due`, `prune`, each atomic on one record — a claim takes `pending`, a due `failed` or a lapsed `processing`; renew and settle only by the attempt holding it |
+| `createTelegramUpdateIntake` | function | webhook updates recorded before Telegram is answered and handled after: chat order kept, other chats alongside up to `maxConcurrent`, a renewed lease and immutable fence per attempt, a sweep that takes over what a restart or a dead process left, retries, `maxAttempts`, optional recoverable exhaustion delivery, finished updates remembered `retainMs` to refuse repeats; at least once |
+| `TelegramUpdateIntakeConfig` / `TelegramUpdateAttemptIntakeConfig` / `TelegramUpdateIntakeOptions` / `TelegramUpdateIntake` / `TelegramUpdateEnvelope` / `TelegramUpdateFailure` / `TelegramUpdateStoreStep` | _type_ | `store`, unchanged `handle(update)` or attempt-aware `handleAttempt(update, context)` (a grammY `BotError` is unwrapped), shared `retry`, `maxAttempts` (5), `leaseMs` (120 000), `pendingGraceMs` (60 000), `sweepEveryMs` (30 000), `retainMs` (24 h), `maxConcurrent` (32), `onFailure`, durable `handleExhaustion`, `onExhaustionFailure`, `onStoreError`, `now`; `accept(body)`, `start()`, `sweep()`, `idle()`, `close()` |
+| `TelegramUpdateAttemptContext` / `TelegramUpdateAttemptIdentity` / `TelegramUpdateOwnershipLostError` | _type_ / class | immutable `{ updateId, attempt, claimId }` fence plus `ownerLost`; the persisted opaque claim token prevents a stale capability from matching after prune/re-add, while a store check in the consumer's DB transaction fences a domain write |
+| `TelegramUpdateExhaustion` / `TelegramUpdateExhaustionFailure` / `StoredTelegramUpdateExhaustion` / `TelegramUpdateExhaustionQuery` | _type_ | a terminal update/attempt/error retained in the update store until `handleExhaustion` resolves; ordered `{ limit, afterUpdateId? }` pages prevent a failing first batch from starving later rows; delivery failures are observational and leave it due |
+| `TelegramUpdateStore` / `StoredTelegramUpdate` / `TelegramUpdateState` / `TelegramUpdateSettlement` / `TelegramUpdateClaimOptions` / `TelegramUpdateDueQuery` | _type_ | the base store an intake runs on: `add`, `claim`, `renew`, `settle`, `due`, `prune`, each atomic on one record — a claim takes `pending`, a due `failed` or a lapsed `processing`; renew and settle only by the attempt holding it |
+| `TelegramUpdateFencedStore` / `TelegramUpdateDurableStore` | _type_ | reference-store capabilities: `claimOwned` creates and returns the persisted identity, `renewOwned`, `owns(identity, at)` and `settleOwned(identity, settlement)` act only on that exact unexpired claim; `exhaust`, `dueExhaustions`, `acknowledgeExhaustion` keep a final consumer obligation in the same row until exact acknowledgement |
 | `memoryTelegramUpdateStore` | function | the store in this process's memory — tests, or a bot that accepts losing unhandled updates to a restart |
 | `sqliteTelegramUpdateStore` / `SqliteTelegramUpdateStoreConfig` / `TelegramSqliteDatabase` | function / _type_ | the store in SQLite over the handle the application opened — `bun:sqlite` `Database` or `node:sqlite` `DatabaseSync`; `table` (default `telegram_updates`) created when missing |
 | `postgresTelegramUpdateStore` / `PostgresTelegramUpdateStoreConfig` / `TelegramPostgresQuery` | function / _type_ | the store in Postgres over the client the application holds, as one `query(text, parameters)` returning rows — Bun `sql.unsafe`, Prisma `$queryRawUnsafe`, `pg` `pool.query`; each rule one conditional statement; `table`, `createTable` (default `true`) |
-| `postgresTelegramUpdateStoreSchema` | function | the table and its index as a statement for a migration, safe to run twice |
+| `postgresTelegramUpdateStoreSchema` | function | the table, idempotent `claim_id` upgrade and index as a statement for a migration, safe to run twice; required before fenced methods when `createTable: false`, while legacy base methods remain compatible with the prior table |
 | `checkTelegramUpdateStore` | function | put any store through every rule, each on a fresh store from `make`, concurrent claims included; resolves with the violations, empty when it keeps them |
 
 ---

package/llms/tools.3.txt

@@ -279,7 +279,7 @@ Advanced building blocks — the shared machinery the mounts are built on.
 | `TransportCounts` | _type_ | per-transport counts (`{ HTTP, MCP, AGENT, CLI }`) |
 | `ToolSurfaceProjection` | _type_ | the one readonly `{ services?, runtimeTools? }` container shared by full, MCP-only and introspection surfaces (`buildToolManifest`, `listToolNames`, `summarizeTransports` take `ToolSurfaceProjection<RuntimeToolDefinition>`) |
 | `ToolManifestConfig` | _type_ | mixed surface plus required model-facing `transport` and presentation options |
-| `coerceJsonArgs` | function | coerce JSON-stringified array/object tool arguments; throws a `ZodError` naming the field when a union that keeps a string member receives a string that parses to an array its array member accepts |
+| `coerceJsonArgs` | function | coerce JSON-stringified array/object tool arguments, including object guards restored from JSON Schema; arbitrary transform pipes stay untouched; throws a `ZodError` naming the field when a union that keeps a string member receives a string that parses to an array its array member accepts |
 | `flattenToolJsonSchema` | function | project structurally identifiable discriminated unions into conservative object joins; scalar collisions retain provable types, object/array collisions retain structural alternatives, and field descriptions retain discriminator labels plus availability/requiredness hints; the projection never executes validation |
 | `ToolPresentationSchema` | _type_ | immutable model-facing JSON Schema document shared by tool transports |
 | `MountableTool` | _type_ | one operation with separate executable CLI argument schema and model-facing presentation schema |

package/llms/{upgrading-0.100.0-0.108.0.txt → upgrading-0.101.0-0.109.0.txt}

@@ -1,14 +1,81 @@
-# Upgrading 0.100.0 → 0.108.0 — stitchkit docs slice
+# Upgrading 0.101.0 → 0.109.0 — stitchkit docs slice
 
 > Generated from the `docs/` tree by `bun run gen:llms`. The index of all slices is
 > `llms.txt` in this package.
 
-Contains: Guide: Upgrading, 0.100.0 → 0.108.0  (docs/guide/upgrading.md)
+Contains: Guide: Upgrading, 0.101.0 → 0.109.0  (docs/guide/upgrading.md)
 
 ==============================================================================
-# Guide: Upgrading, 0.100.0 → 0.108.0  (docs/guide/upgrading.md)
+# Guide: Upgrading, 0.101.0 → 0.109.0  (docs/guide/upgrading.md)
 ==============================================================================
 
+## Released migration: 0.109.0
+
+### free CLI record leaves are lexical
+
+**Who must act:** scripts that pass dotted values into a free `record<string, unknown>` and rely on
+stitchkit guessing numbers or booleans from their spelling. Declared object leaves and whole-object
+JSON keep their typed behavior.
+
+Free record values have no schema type to justify coercion. They now preserve argv text, so values
+such as `007`, `1e3`, `true` and `false` arrive exactly as written.
+See [ADR 0257](../decisions/0257-cli-dotted-values-follow-their-declared-schema.md).
+
+1. Pass typed free-record values as one JSON object:
+
+   ```sh
+   # before: produced { count: 5 } by spelling-based inference
+   app command --data.count=5
+   # after: JSON says explicitly that 5 is a number
+   app command --data='{"count":5}'
+   ```
+
+2. If dotted flags are the intended interface, declare their object shape; a `z.number()` or
+   `z.boolean()` leaf still coerces and validates its own CLI value.
+
+### Opting into Telegram attempt fencing
+
+Existing `handle(update)` callbacks and the six-method `TelegramUpdateStore` need no change. The
+new capability is opt-in
+([ADR 0256](../decisions/0256-a-telegram-attempt-is-fenced-by-a-persisted-claim.md)).
+
+1. To fence a domain write, move only that handler to the explicit context-aware option:
+
+   ```ts
+   createTelegramUpdateIntake({
+     store,
+     handleAttempt: async (update, { fence, ownerLost }) => {
+       ownerLost.throwIfAborted()
+       await domainTransaction(async (tx) => {
+         if (await transactionStore(tx).owns(fence, Date.now())) await apply(tx, update)
+       })
+     },
+   })
+   ```
+
+2. A direct grammY handler remains `handle: bot.handleUpdate.bind(bot)`; stitchkit does not pass its
+   attempt context into grammY's optional webhook-envelope parameter.
+
+3. A custom store used by `handleAttempt` implements `claimOwned`, `renewOwned`, `owns` and
+   `settleOwned` over the full `{ updateId, attempt, claimId }` identity. If it also delivers
+   `handleExhaustion`, implement `exhaust`, `dueExhaustions` and `acknowledgeExhaustion`. Run
+   `checkTelegramUpdateStore` against a fresh database; it checks base, fenced and durable rules
+   according to the methods the store exposes.
+
+4. SQLite stores add `claim_id` automatically. PostgreSQL stores with the default
+   `createTable: true` do the same. When migrations own a PostgreSQL table, apply the returned
+   schema before enabling `handleAttempt` or `handleExhaustion`:
+
+   ```ts
+   await sql.unsafe(postgresTelegramUpdateStoreSchema('telegram_updates'))
+   // Equivalent addition for an existing table:
+   // ALTER TABLE telegram_updates ADD COLUMN IF NOT EXISTS claim_id TEXT;
+   ```
+
+   Legacy `handle(update)` continues to use base operations that do not reference `claim_id`, so
+   the migration is required only when the new capability or an explicit base
+   `claim(..., { durableExhaustion: true })` is enabled.
+
 ## Released migration: 0.108.0
 
 ### a request that never left is its own send outcome
@@ -831,72 +898,3 @@ text.replace(new RegExp(TELEGRAM_BOT_TOKEN_PATTERN.source, 'g'), '[redacted]')
 createJsonLogger({})
 redactTelegramBotToken(text)
 ```
-
-## Released migration: 0.100.0
-
-### watch capacity and session/live/delivery adoption
-
-**Who must act:** watch consumers exceeding 1024 hub sources, 1024 hub subscribers,
-1024 client keys or 128 listeners per key. These previously unbounded collections
-now refuse excess admission. Choose explicit positive finite limits, for example:
-
-```ts
-// Before: no hub-wide capacity bounds.
-createWatchHub({ read, watchable });
-// After: explicitly budget a larger workload.
-createWatchHub({ read, watchable, maxSources: 4096, maxSubscribers: 4096 });
-// Client limits are configured independently.
-createWatchClient({ ...clientConfig, maxKeys: 2048, maxListenersPerKey: 256 });
-```
-
-The remaining steps apply only to applications opting into session lifetimes,
-scoped watched reads, managed subscriptions or multi-action notification delivery.
-Existing clients within the limits and single-send outboxes need no migration.
-
-Replace local session generation counters with one `createSessionScope`; share it
-with `createSessionCredentials`. Guard transport attempts, complete asynchronous
-operations and final synchronous delivery. Route credential persistence through
-one coordinator. Keep provider-specific error classification and bounded command
-retry in the application. Coordination is per client instance.
-
-Upgrade both watch endpoints before enabling session-scoped watches: strict older
-servers reject the new optional `WatchKey.instance`. Server-verified scope controls
-sharing; the client instance is only routing identity. Bind exact watched handles
-to session-qualified cache keys. Existing delta/reconnect behavior stays in place.
-For applications needing more than 1024 hub sources/subscribers or client keys, set
-explicit finite capacity options. Enable a reconciliation interval when lost hints
-must recover without a reconnect.
-
-For multi-action outboxes, enqueue new items with a versioned delivery plan and
-return small JSON receipts from `send`. Existing queued single-send items should
-be drained before enabling a delivery executor on that queue, or migrated under
-the store's atomic transition. When a new executor version ships, list the old
-version's projection in `delivery.retiredVersions` until its queued items drain;
-a plan version with no executor waits, reported to `onError` as
-`NotificationPlanVersionError` (from 0.100.1).
-Make projection idempotent. Provider idempotency/reconciliation remains necessary
-for a crash between remote success and checkpoint. These APIs are available starting with 0.100.0.
-
-### exclusive lock recovery
-
-New lock and reclaim-guard records include `owner.process`: kernel boot identity,
-process birth token and namespace. `readDiagnosticJournalLockDiagnosis(error)`
-adds `identity` to distinguish matched lifetime evidence, PID reuse, a different
-boot, an absent PID, a legacy record or unavailable identity. Legacy `alive` only
-means the PID is present; it does not prove that the recorded writer still exists.
-
-**Who must act:** deployments recovering a legacy lock with a reused live PID,
-or bundling file-lock consumers into a standalone Darwin executable. Legacy
-records cannot safely infer their missing boot/start identity from `acquiredAt`.
-Stop all writers to that resource, verify exclusive ownership, preserve the old
-lock for incident evidence outside the active lock path, and restart with the
-new package. Never delete a lock merely because it is old. New acquisitions
-write the modern record; no journal data migration is needed.
-
-Darwin distributions must retain the package's architecture-matched native
-`.node` asset for process birth measurement, as for contained filesystem access.
-If native/proc identity cannot be read, new locks explicitly record null and
-recovery refuses rather than treating unknown ownership as death. From 0.100.1 a
-Linux kernel without time namespaces (before 5.6) records the PID namespace alone
-instead of null, so its locks recover like any other. Existing
-`refuse` policy and the separately configured ownerless-file grace are unchanged.

package/llms/upgrading-0.37.0.txt

@@ -0,0 +1,176 @@
+# Upgrading 0.37.0 → 0.37.0 — stitchkit docs slice
+
+> Generated from the `docs/` tree by `bun run gen:llms`. The index of all slices is
+> `llms.txt` in this package.
+
+Contains: Guide: Upgrading, 0.37.0 → 0.37.0  (docs/guide/upgrading.md)
+
+==============================================================================
+# Guide: Upgrading, 0.37.0 → 0.37.0  (docs/guide/upgrading.md)
+==============================================================================
+
+## The 0.37 migration
+
+Tool presentation is no longer an executable Zod parser. Replace the removed
+flatten helpers with the JSON Schema compiler, and choose the explicit
+`MountableTool` surface when using the advanced collection API:
+
+```ts
+// before
+const flat = flattenUnionsDeep(zodSchema)
+mountable.schema
+
+// after
+const flat = flattenToolJsonSchema(
+  z.toJSONSchema(zodSchema, { target: 'draft-07', io: 'input' }),
+)
+mountable.presentationSchema // model/MCP/manifest JSON Schema
+mountable.argumentSchema     // executable CLI argument adapter only
+```
+
+Contract and native handlers keep their original Zod schemas; MCP and agent SDK
+adapters now forward raw arguments so defaults, coercions, refinements and
+transforms execute exactly once inside Stitchkit. There are no compatibility
+exports for `flattenDiscriminatedUnion`, `flattenUnionsDeep` or
+`MountableTool.schema`. → ADR 0050
+
+Tool-call hooks now take one options object. Migrate all three callbacks; there
+are no positional overloads:
+
+```ts
+// before
+beforeToolCall: (toolName, args, context, endpoint) => {}
+afterToolCall: (toolName, args, result, durationMs, context, endpoint, error) => {}
+onToolError: (toolName, error, context, endpoint) => {}
+
+// after
+beforeToolCall: ({ toolName, args, context, endpoint }) => {}
+afterToolCall: ({ toolName, args, result, durationMs, context, endpoint, error }) => {}
+onToolError: ({ toolName, error, context, endpoint }) => {}
+```
+
+### MCP schema validation
+
+The standalone validator now takes one object and live MCP configs carry the
+same rules under `schemaValidation`. Migrate every positional call and every
+`onIncompatibleSchema` field; there is no old-shape overload:
+
+```ts
+// before
+validateMcpSchemas(services, 'throw', logger, { requireTypedProperties: true })
+createMcpHandler({ services, onIncompatibleSchema: 'throw' })
+
+// after
+validateMcpSchemas({ services, policy: 'throw', logger, requireTypedProperties: true })
+createMcpHandler({ services, schemaValidation: { policy: 'throw' } })
+```
+
+Put `extend` and `flattenUnionInput` beside `services`, not inside
+`schemaValidation`. The handler applies the profile to the exact prepared schema
+it advertises. Add `requirePortableFormats: true` when every custom JSON Schema
+format must be rejected before a client sees it.
+
+Native MCP registration also changed shape in 0.37. Move protected tools to the
+framework registrar; keep an SDK-raw tool only by naming the opt-out:
+
+```ts
+// before
+nativeTools: (server, auth) => server.registerTool(name, config, handler)
+
+// after — lifecycle, hooks and schema policy apply
+nativeTools: ({ registerTool }, auth) => registerTool({
+  name, description, identity, input, output, handler,
+})
+
+// after — intentionally raw
+nativeTools: ({ rawServer }, auth) => rawServer.registerTool(name, config, handler)
+```
+
+If a tool hook annotated `endpoint` as `MethodDef`, remove that annotation or
+use `OperationIdentity`: native operations have service/action/scope/method but
+no HTTP path.
+
+### Node-facing server types
+
+`stitchkit/server` remains Bun-concrete: an explicitly annotated `RawRoute`
+still receives `BunServer`. `stitchkit/node` no longer drags Bun declarations
+into a Node project. Its raw routes default the host server to `unknown`, and
+its Socket.IO handle exposes only Node capabilities:
+
+```ts
+// before — Node entry still leaked Bun-only fields and ambient types
+const route: RawRoute = { handler: (_req, ctx) => ctx.server?.upgrade(...) }
+const socket = await createSocketIOServer(config)
+socket.websocket
+
+// after — name a custom embedding host only when one exists
+const route: RawRoute<MyHostServer> = {
+  handler: (_req, ctx) => useHost(ctx.server),
+}
+const socket = await createSocketIOServer(config)
+socket.io
+socket.attach(nodeHttpServer)
+```
+
+Node consumers can remove `@types/bun` unless another dependency independently
+requires it.
+
+### Managed server shutdown
+
+`createServer()` and `serveNode()` now return the same structural managed
+lifecycle. Replace every direct runtime stop and parallel Socket.IO close:
+
+```ts
+// before — split ownership
+const socket = await createSocketIOServer(config)
+const server = createServer({
+  services,
+  websocket: socket.websocket,
+  rawRoutes: [socket.route],
+})
+server.stop()
+await socket.io.close()
+
+// after — one owner and one total deadline
+const socket = await createSocketIOServer(config)
+const server = createServer({ services, socket })
+const result = await server.shutdown({ gracePeriodMs: 30_000 })
+```
+
+On Node, keep the same `socket` field and replace `handle.close()` with
+`handle.shutdown()`. Runtime-specific diagnostics move under `handle.runtime`;
+do not use it as a second shutdown path. Standalone CLI/tools that create a
+Socket.IO handle without an HTTP server call `await socket.close()`.
+
+If Bun Socket.IO shares the port with a raw lane, keep the explicit composition
+but let the server mount the Socket.IO route:
+
+```ts
+createServer({
+  services,
+  socket,
+  websocket: composeWebSocketHandlers([
+    webSocketLane({ match: isRaw, handlers: rawHandlers }),
+    socketIoLane(socket.websocket),
+  ]),
+  rawRoutes: [rawUpgradeRoute],
+})
+```
+
+Move native Bun `routes` entries to `rawRoutes`. Native routes run before the
+Fetch handler and therefore cannot participate in admission or drain. Wire
+`SIGTERM`/`SIGINT` in the application; the first signal starts `shutdown()`, and
+a later signal may abort the same controller. Close MCP, databases and queues
+after the server result—those resources remain application-owned.
+
+Move a handshake policy from the Node-only callback shape inside
+`serverOptions` to the runtime-neutral top-level policy. It receives a Web
+`Request`, may be async, and returns whether to admit the handshake:
+
+```ts
+// before
+serverOptions: { allowRequest: (request, done) => done(null, allowed(request)) }
+
+// after
+allowRequest: (request) => allowed(request)
+```