stitchkit 0.49.2 → 0.51.0

package/llms-full.txt

@@ -617,6 +617,21 @@ the exact config without `NonNullable` or another wrapper. Plain `ContractDef`
 keeps optional scope because ordinary `defineContract` still supports its
 default-public overload.
 
+The union covers **per-endpoint overrides too**, not just the contract's scope —
+that is where typos are densest, and one there used to compile and then fail
+closed at request time (`[stitchkit] auth: no rule for scope "…"`):
+
+```ts
+defineContract({ prefix: 'posts', scope: 'user' }, {
+  drop: { method: 'DELETE', path: '/:id', desc: 'Drop', scope: 'admn', … },
+  //                                              ^ compile error, and TypeScript
+  //                                                suggests 'admin'
+})
+```
+
+Contracts built with plain `defineContract` are unaffected — their endpoint
+`scope` stays a free string.
+
 ## One source of truth
 
 A contract is plain data — no classes, no decorators, no codegen. It is imported
@@ -686,6 +701,79 @@ export const implement = createImplement<AppContext>()
 // every implement() call now has ctx.user typed
 ```
 
+### Per-scope handler context — `createScopedImplement`
+
+`createImplement<Ctx>()` gives every handler the **same** context type. In an app
+where each scope guarantees different injected fields, that single type is a
+superset: a `public` handler is told it has a `userId` the runtime never injects
+there. `createScopedImplement` types each handler by its endpoint's **effective**
+scope instead — the endpoint's own `scope`, else the contract's:
+
+```ts
+import { createScopedImplement } from 'stitchkit/server'
+
+export const implementFor = createScopedImplement<{
+  public: object                                 // no extra fields
+  user: { userId: string }
+  admin: { userId: string; isAdmin: boolean }
+}>()
+
+implementFor(postsContract, {
+  list: (ctx) => listPosts(ctx.userId),          // contract scope 'user'
+  purge: (ctx) => (ctx.isAdmin ? purge() : []),  // endpoint scope 'admin'
+  ping: () => ({ ok: true }),                    // endpoint scope 'public'
+})
+```
+
+The map is **type-only** — scope fields are types, so there is no runtime
+argument and no `{} as UserFields` at the call site. `'public'` must be a key:
+a contract without a `scope` is `'public'`. A scope outside the map is a compile
+error on that endpoint, naming the scope.
+
+Three boundaries worth knowing:
+
+- A field of another scope is not a compile error on access — `RuntimeContext`
+  keeps its `[key: string]: unknown` index signature (transports write through
+  it). It degrades to `unknown`, so it can no longer pose as a `string`; using it
+  in a typed position fails.
+- The map states what **your** `beforeHandle` / `createAuthHook.inject` puts on
+  the context. The framework does not verify a hand-written claim (→ ADR 0075) —
+  so prefer not to write one: scoped auth rules declare their contribution by
+  performing it, and `createScopedImplement<AuthScopes<typeof hook>>()` derives
+  the map from the hook
+  ([details](./auth-and-errors.md#scoped-rules--the-map-createscopedimplement-consumes),
+  → ADR 0078).
+- An endpoint hoisted out of the contract literal widens its `scope` to `string`,
+  which is no key of any map, and lands in the error branch. An endpoint whose
+  `scope` is added by a conditional spread is optional, so it resolves to **both**
+  scopes and is typed against what they guarantee in common. Write endpoints
+  inline for the precise type.
+- Scope keys are string literals. A map declared as an index signature
+  (`Record<string, …>`) makes every scope valid and disables the check.
+
+The same map has a registry form and a streaming form:
+
+```ts
+// one contract registry, handlers still typed per endpoint scope
+const implementAll = createScopedImplementRegistry<Scopes>()
+export const services = implementAll(apiContractRegistry, { posts, users })
+
+// a streaming multipart handler that reads its scope's fields. The endpoint
+// must declare its own `scope`, and only that literal is accepted: an endpoint
+// inheriting the contract's scope cannot be verified from here, and guessing it
+// would rebuild the superset this factory removes.
+implementFor(mediaContract, {
+  upload: implementFor.stream('admin', mediaContract.endpoints.upload, {
+    files: { file: receiveFile },
+    handler: ({ files, userId }) => store(files.file, userId),
+  }),
+})
+```
+
+Outside a scoped app, `createMultipartStream<Ctx>()` does for streaming handlers
+what `createImplement<Ctx>()` does for ordinary ones. Plain
+`defineMultipartStream` still gives the loose `RuntimeContext`.
+
 ### `implementRegistry` — one backend registry
 
 When contracts already live in one literal registry, bind the backend from that
@@ -702,7 +790,17 @@ export const apiServices = implementRegistry(apiContractRegistry, {
 
 Every registry key is required, extra keys fail, and each handler map is checked
 against its own contract. The returned service order follows the contract
-registry order. `createImplementRegistry<AppContext>()` fixes the application
+registry order — and the same services ride along under `.byKey`, so a consumer
+whose registry keys are load-bearing (filtering a tool surface per caller) never
+rebuilds a prefix lookup by hand:
+
+```ts
+const services = implementRegistry(apiContractRegistry, handlers)
+createServer({ services })                       // the array, as before
+const visible = [services.byKey.users]           // the same objects, by key
+```
+
+`createImplementRegistry<AppContext>()` fixes the application
 context once, like `createImplement` does for a single contract. Runtime callers
 also fail first on missing/extra keys and duplicate contract prefixes.
 
@@ -974,9 +1072,11 @@ createServer({
 
 A prefix may carry `:param` segments (they land on the context exactly as above).
 Services listed under explicit `groups` are unaffected — the group prefix wins.
-Scope stays a free string; the core attaches no meaning beyond this lookup
-(→ ADR 0024). When each scope needs a different handler-context shape, declare one
-`createImplement<Ctx>()` per scope rather than a single superset context.
+Scope stays a free string (unless the contract is authored through
+`createContractFactory<Scope>()`); the core attaches no meaning beyond this lookup
+(→ ADR 0024). When each scope needs a different handler-context shape, use
+[`createScopedImplement`](#per-scope-handler-context--createscopedimplement)
+rather than a single superset context.
 
 ## Lifecycle hooks
 
@@ -3578,7 +3678,9 @@ the scope vocabulary are yours.
 ## Scopes
 
 An endpoint declares a `scope` — a free string. The contract `meta.scope` is the
-default for endpoints that declare none.
+default for endpoints that declare none. (Authored through
+[`createContractFactory<Scope>()`](./contracts.md#scope), both the contract's
+scope and any endpoint override are held to your own union instead.)
 
 ```ts
 export const posts = defineContract({ prefix: 'posts', scope: 'user' }, {
@@ -3668,7 +3770,61 @@ endpoints under the group declare `scope: 'tenant'`.
 | `onForbidden` | thrown when an identity is present but the rule rejects it (default 403) |
 
 Annotate `rules` with `satisfies Record<MyScope, AuthRule<User>>` so the compiler
-catches a scope you forgot to cover.
+catches a scope you forgot to cover. With the scoped rule objects below, widen
+the annotation to
+`satisfies Record<MyScope, AuthRule<User> | ScopedAuthRule<User, object>>` — it
+keeps the coverage check and does not disturb the derivation. (When every scope
+comes from the derived map, the check is already implicit: a scope missing from
+`rules` is no key of the map, and a contract using it fails to compile.)
+
+### Scoped rules — the map `createScopedImplement` consumes
+
+A rule may take an object form, `{ rule, inject }`, where `inject` **returns**
+the fields this scope contributes. That return type is a declaration the hook
+derives a scope→context map from — feed it to
+[`createScopedImplement`](./server.md#per-scope-handler-context--createscopedimplement)
+and the map can never drift from the hook, because it is computed from it:
+
+```ts
+const authHook = createAuthHook({
+  resolve: sessionResolver,             // no explicit generic — let it infer
+  rules: {
+    public: { rule: 'public', inject: (user) => ({ userId: user.id }) },
+    user: { rule: 'authenticated', inject: (user) => ({ userId: user.id }) },
+    admin: {
+      rule: (user) => user.admin,
+      inject: (user) => ({ userId: user.id, isAdmin: user.admin }),
+    },
+  },
+})
+
+export const implementFor = createScopedImplement<AuthScopes<typeof authHook>>()
+```
+
+- A `'public'` rule's fields come out **optional**: public admits the anonymous
+  caller, it does not refuse to know the logged-in one — `resolve` and `inject`
+  still run, so a public `me` / `logout` handler reads `ctx.userId` as
+  `string | undefined` and narrows, instead of being pushed toward a cast by a
+  `public: object` map.
+- Any other rule's fields are required — the rule rejected the request before
+  the handler if no identity resolved.
+- A scope with no rule is no key of the derived map, so a contract using it
+  fails to compile — the type-level mirror of the hook's fail-closed
+  `no rule for scope` throw.
+
+The per-rule `inject` runs after the shared one, only when an identity
+resolved, and **before** the rule check — it may run for an identity the rule
+then rejects, so keep it pure and synchronous (an async `inject` is a compile
+error, and a runtime one for untyped callers: merging a Promise would merge
+nothing). Write rule objects inline in `rules` — a hoisted, annotated rule
+widens its inject and degrades that scope's fields to `object`.
+
+Derivation needs the identity generic to be **inferred** (write no explicit
+`createAuthHook<User>` — TypeScript has no partial inference); with an explicit
+generic, or fields injected outside the hook, keep the hand-written map. Two
+hooks guarding different scopes compose by intersection:
+`createScopedImplement<AuthScopes<typeof userHook> & AuthScopes<typeof botHook>>()`.
+→ ADR 0078
 
 ### Auth on the tool surface — `resolveFromContext`
 
@@ -3870,36 +4026,57 @@ onError: (ctx, err) => {
 
 ## Domain errors — `defineErrors`
 
-Declare each domain code, HTTP status and optional structured-details schema in
-one immutable registry. The generated functions construct typed branded
-`AppError` instances; ordinary `throw` remains explicit at the call site:
+Declare each domain code, HTTP status, default message and optional
+structured-details schema in one immutable registry. The generated functions
+construct typed branded `AppError` instances; ordinary `throw` remains explicit
+at the call site:
 
 ```ts
 import { z } from 'zod'
 
 export const { errors, codes, definitions, isCode } = defineErrors({
-  SESSION_NOT_FOUND: { status: 404 },
+  SESSION_NOT_FOUND: { status: 404, message: 'No such session' },
   QUOTA_EXCEEDED: {
     status: 429,
+    message: 'Monthly quota exhausted',
     details: z.object({ retryAfterSeconds: z.number().int().positive() }),
   },
 })
 
-throw errors.SESSION_NOT_FOUND({ message: 'No such session' })
+throw errors.SESSION_NOT_FOUND()                      // uses the declared message
 throw errors.QUOTA_EXCEEDED({
-  message: 'Try later',
+  message: 'Try later',                               // overrides it here only
   details: { retryAfterSeconds: 30 },
   hint: 'Wait for the current window to expire',
 })
 
 // Construction without throwing is useful for composition or inspection.
 const error = errors.QUOTA_EXCEEDED({ details: { retryAfterSeconds: 30 } })
-definitions.QUOTA_EXCEEDED.status // 429 — same source, no copied status map
+definitions.QUOTA_EXCEEDED.status  // 429 — same source, no copied status map
+definitions[code].message          // the declared text, by a `code` variable
 
 // client — match the code, never a magic string
 if (err instanceof ApiError && err.code === codes.SESSION_NOT_FOUND) { … }
 ```
 
+`message` is optional: declare it once instead of repeating the sentence at every
+`throw`, and a per-call `message` still wins. A code without one keeps the
+existing fallback — `AppError.message` is the code itself. An empty declared
+message is rejected when the registry is declared, not when the error is thrown.
+
+**The tool envelope has no `message` field**, and what the model sees depends on
+whether the code declares `details`:
+
+| | HTTP / typed client | MCP / agent / CLI |
+|---|---|---|
+| code **with** a `details` schema | the declared message | no text at all — only `details` and `hint` |
+| code **without** one | the declared message | the same text, delivered as `details.message` |
+
+The model-facing envelope is `{ error, details?, _hint? }`; for a code with no
+details schema the framework fills `details` with `{ message }`, so declaring a
+message changes what the model reads there — it used to be the code itself. Put
+anything the model must reliably read in `details` or `hint`, not in `message`.
+
 With no `details` schema, the options object forbids `details`. A required
 `z.object` makes `details` required; `z.object(...).optional()` makes it
 optional. Supplied details are parsed when the error is constructed, before any
@@ -4637,34 +4814,123 @@ createServer({
 })
 ```
 
-Keep the managed handle and wire process policy explicitly:
+### Process signals — `bindProcessSignals`
+
+Keep the managed handle and wire process policy explicitly. The framework
+registers no signal listener on its own; `bindProcessSignals` is that explicit
+step, and it owns the state machine:
 
 ```ts
+import { bindProcessSignals } from 'stitchkit/server'
+
 const server = createServer({ services, socket })
-const force = new AbortController()
-let closing: Promise<void> | undefined
 
-function shutdown() {
-  if (closing) {
-    force.abort() // a later signal shortens the same shutdown, not a second chain
-    return closing
-  }
-  closing = server.shutdown({
-    gracePeriodMs: 30_000,
-    forceTimeoutMs: 5_000,
-    signal: force.signal,
-  }).then(async result => {
+bindProcessSignals(server, {
+  shutdown: { gracePeriodMs: 30_000, forceTimeoutMs: 5_000 },
+  onShutdown: () => stopSchedulers(),        // before the drain starts
+  onComplete: async (result) => {            // after it finishes
     await mcp.close()
     await prisma.$disconnect()
-    console.log(result)
-  })
-  return closing
+    process.exitCode = result.outcome === 'clean' ? 0 : 1
+  },
+  onError: (error) => {
+    console.error(error)
+    process.exitCode = 1
+  },
+})
+```
+
+- The first signal runs `onShutdown`, then one `shutdown()`.
+- A later signal **forces that same chain** — never a second shutdown. Signals
+  delivered in the same turn as the first (a supervisor sending `SIGINT` and
+  `SIGTERM` together) are not counted, so the grace period is not collapsed to
+  zero.
+- The signal after the force — or one arriving while `onComplete` still runs —
+  re-delivers the signal so its default disposition applies, letting an operator
+  kill a process stuck on some other resource. This works only while nothing else
+  in the process listens for that signal; if something does, the signal is
+  swallowed and `onEscalationBlocked` fires instead. The framework will not call
+  `process.exit` on your behalf.
+- `shutdown` budgets are validated when you bind, not when the signal arrives.
+  `signal` is not accepted there — the binding owns it, and that is what makes a
+  later signal force the first chain.
+- `onError(phase, error)` separates the phases. A failing `onShutdown`
+  (`'prepare'`) is reported and the shutdown **still runs** — a failed
+  preparation must not leave the server listening. A failing `onComplete`
+  (`'complete'`) leaves `promise` resolved, because the transport did shut down.
+  Only a failing `shutdown()` (`'shutdown'`) rejects it.
+
+`close()` removes the listeners. Closing a binding that never received a signal
+resolves `promise` with `undefined`, so an awaiting application does not hang;
+closing one whose chain is already running leaves that chain to finish and keeps
+the handle claimed, since a second binding could not force it. `promise` is
+already observed internally, so ignoring it never raises an `unhandledRejection`.
+
+#### Composite shutdown target — parallel domain drains
+
+`bindProcessSignals` takes `Pick<ManagedServerHandle, 'shutdown'>` — an
+**interface**, not the server. An application whose shutdown spans several
+domains (transport, bots, agent runs, broadcasts) composes them into one target;
+the signal machine stays the framework's, the composition stays yours:
+
+```ts
+const composite: ShutdownTarget = {
+  async shutdown(options?: ShutdownOptions): Promise<ShutdownResult> {
+    const { signal } = ShutdownOptionsSchema.parse(options ?? {})
+    // Domain drains run in parallel with the transport drain, all watching the
+    // same force signal the second OS signal aborts.
+    const [transport, bots, agents, broadcasts] = await Promise.all([
+      server.shutdown(options),
+      drainBots(signal),
+      drainAgents(signal),
+      drainBroadcasts(signal),
+    ])
+    return {
+      ...transport,
+      // Fold domain leftovers into the transport result so `onComplete` sees
+      // one honest outcome.
+      outcome: transport.outcome === 'clean' && bots + agents + broadcasts === 0
+        ? 'clean'
+        : 'forced',
+    }
+  },
 }
 
-process.on('SIGTERM', () => void shutdown())
-process.on('SIGINT', () => void shutdown())
+bindProcessSignals(composite, { shutdown: { gracePeriodMs: 30_000 } })
+```
+
+The transport half inside stays the real managed handle — its admission gate and
+HTTP drain are not reimplemented, only composed. Domain drains must watch the
+`signal` themselves: it is the only channel a second OS signal has into a
+running chain.
+
+#### The last line of defence is yours
+
+The framework never calls `process.exit`, and `process.exitCode` only takes
+effect once the event loop empties — which is exactly what a stuck resource
+prevents. If the deployment must exit before the supervisor's `SIGKILL`, arm an
+application-side timer:
+
+```ts
+onShutdown: () => {
+  setTimeout(() => process.exit(1), 60_000).unref()
+},
 ```
 
+`unref()` keeps the timer from holding a healthy process open; it only fires if
+something else already is.
+
+#### When NOT to use `bindProcessSignals`
+
+- The application already runs a signal machine with states this one does not
+  have (staged escalation policies, per-signal semantics beyond
+  first/force/escalate). Two machines on the same signals is worse than either.
+- Signal policy must differ per signal (e.g. `SIGHUP` = reload, not shutdown) —
+  bind only the terminating signals here and keep the rest yours.
+- Something else in the process must keep listening for the same signal: the
+  escalation path restores the default disposition only when nothing else
+  listens, and reports `onEscalationBlocked` otherwise.
+
 The server owns HTTP/Socket.IO transport resources. MCP, databases, queues and
 domain run-state remain application resources and close explicitly after server
 drain. Do not call `runtime.stop()` or `socket.io.close()` in parallel with
@@ -4797,10 +5063,20 @@ createServer({
 Handlers read `ctx.tenantId` (a raw `string` — narrow it). To get it typed inside
 `ctx.params`, add `tenantId` to the endpoint's `params` schema (a `z.strictObject`
 that omits it will reject the request). When each scope guarantees different
-injected fields, call `createImplement<TenantCtx>()` / `createImplement<BaseCtx>()`
-**once per scope** and implement each contract with the matching factory — every
-handler is typed to its scope, with no superset context that lies about a
-`tenantId` a `public` handler never has.
+injected fields, declare the scope map once with
+[`createScopedImplement`](./server.md#per-scope-handler-context--createscopedimplement):
+
+```ts
+export const implementFor = createScopedImplement<{
+  public: object
+  tenant: { tenantId: string; userId: string }
+  project: { projectId: string; userId: string }
+}>()
+```
+
+Each handler is then typed by its endpoint's effective scope — no superset
+context that promises a `tenantId` a `public` handler never receives. A contract
+that mixes scopes across its endpoints needs no splitting.
 
 ## 3. Auth — gate the tenant in the path
 
@@ -4990,6 +5266,69 @@ current one *up to* your target, and apply each snippet.
    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.50.0
+
+### The factory's scope union now covers per-endpoint overrides
+
+`createContractFactory<Scope>()` already required a typed `scope` on the
+contract. It now holds a per-endpoint `scope` override to the same union. Nothing
+to migrate unless an override is outside the union — which was always a bug: the
+scope reached no auth rule, and `createAuthHook` threw
+`[stitchkit] auth: no rule for scope "…"` on the first request to it.
+
+```ts
+const { defineContract } = createContractFactory<'public' | 'user' | 'admin'>()
+
+defineContract({ prefix: 'posts', scope: 'user' }, {
+  // before: compiled; failed at request time
+  // after:  compile error naming the scope (TypeScript even suggests 'admin')
+  purge: { method: 'DELETE', path: '/all', desc: 'Purge', scope: 'admn', output },
+})
+```
+
+Fix the typo, or widen the factory union if the scope is real. Contracts built
+with plain `defineContract` are unaffected.
+
+### A declared `defineErrors` message is now used
+
+`ErrorDefinition` accepts `message`. Nothing to migrate unless a registry already
+wrote that key: it type-checked before (excess-property checking does not fire
+through a `const` generic) and was ignored, so the code itself went on the wire.
+
+```ts
+const { errors } = defineErrors({ GONE: { status: 410, message: 'Long gone' } })
+// before: errors.GONE().message === 'GONE'
+// after:  errors.GONE().message === 'Long gone'
+```
+
+If a registry carried `message` as a note to the reader rather than as
+user-facing text, either fix the text or drop the key. A code with no `details`
+schema also shows that text to a model (its tool `details` is `{ message }`).
+
+### Optional: adopt `createScopedImplement`
+
+If the app declares one superset handler context because different scopes inject
+different fields, replace it with a scope map. This is additive — `createImplement`
+still works.
+
+```ts
+// before — one context for every scope; `ctx.userId` is typed even in a
+// `public` handler, where the runtime never injects it
+interface AppContext extends RuntimeContext { userId: string; isAdmin: boolean }
+export const implement = createImplement<AppContext>()
+
+// after — each handler typed by its endpoint's effective scope
+export const implementFor = createScopedImplement<{
+  public: object
+  user: { userId: string }
+  admin: { userId: string; isAdmin: boolean }
+}>()
+```
+
+`'public'` must be a key (a contract with no `scope` is `'public'`). Write
+endpoints inline in the contract literal: an endpoint hoisted into a variable
+widens its `scope` to `string` and is reported as undeclared.
+
 ## Released migration: 0.48.0
 
 ### Typed-client request options move to `.withOptions`
@@ -5919,13 +6258,14 @@ from the root `stitchkit`.
 | Export | Kind | Summary |
 |--------|------|---------|
 | `defineContract` | function | declare a contract — [guide](../guide/contracts.md#definecontract) |
-| `createContractFactory` | function | a `defineContract` with a required allowed scope that retains each concrete literal — [guide](../guide/contracts.md#scope) |
+| `createContractFactory` | function | a `defineContract` whose scope — on the contract **and** on any endpoint override — is required and held to your union, retaining each concrete literal — [guide](../guide/contracts.md#scope) |
 | `ContractFactoryConfig` | _type_ | optional scoped-factory policy, including explicit tool exposure |
 | `ContractFactoryToolExposure` | _type_ | `'explicit'` — omitted endpoint exposure materializes as HTTP-only |
 | `ExplicitScopedDefineContract` | _type_ | scoped factory authoring with explicit tool opt-in |
 | `ExplicitToolExposureEndpoints` | _type_ | endpoint map after missing exposure is materialized as `['HTTP']` |
+| `FactoryScopedEndpoint` | _type_ | an endpoint authored through the factory — its own `scope` override is held to the same union |
 | `ScopedContractDef` | _type_ | a factory-defined contract whose `meta.scope` is the required concrete literal |
-| `ScopedDefineContract` | _type_ | the `defineContract` `createContractFactory` returns |
+| `ScopedDefineContract` | _type_ | the `defineContract` `createContractFactory` returns — endpoint `scope` overrides join the union |
 | `ALL_TRANSPORTS` | constant | `['HTTP', 'MCP', 'AGENT', 'CLI']` |
 | `ContractDef` | _type_ | a defined contract |
 | `ContractMeta` | _type_ | a contract's `prefix` + optional `scope` and `meta` (a default every endpoint shallow-merges over) |
@@ -5975,7 +6315,7 @@ from the root `stitchkit`.
 | `defineErrors` | function | declare immutable domain error definitions → typed `AppError` constructors, codes and schemas — [guide](../guide/auth-and-errors.md#domain-errors--defineerrors) |
 | `DefinedErrors` | _type_ | the `{ errors, codes, definitions, isCode }` handle `defineErrors` returns |
 | `DefinedAppError` | _type_ | literal-code error instance with schema-refined details |
-| `ErrorDefinition` | _type_ | `{ status, details? }` definition for one domain code |
+| `ErrorDefinition` | _type_ | `{ status, message?, details? }` definition for one domain code |
 | `ErrorDefinitions` | _type_ | string-keyed domain error definition registry |
 | `ErrorDetailsSchema` | _type_ | required or optional Zod object accepted for structured details |
 | `ErrorDetailsOutput` | _type_ | parsed details inferred from one definition |
@@ -6011,9 +6351,19 @@ Also re-exports the error helpers from `stitchkit/contract`.
 | `createHandler` | function | the router as a bare `(req) => Response` — [guide](../guide/server.md#createserver) |
 | `implement` | function | bind a contract to typed handlers — [guide](../guide/server.md#implement) |
 | `createImplement` | function | fix the handler context type once |
+| `createScopedImplement` | function | fix one scope→context map, then type every handler by its endpoint's effective scope — [guide](../guide/server.md#per-scope-handler-context--createscopedimplement) |
+| `ScopedHandlers` | _type_ | handler map typed per endpoint by its effective scope |
+| `ScopeContexts` | _type_ | scope → extra context fields map accepted by `createScopedImplement` |
+| `EffectiveScope` | _type_ | an endpoint's own `scope`, else its contract's group scope |
+| `createScopedImplementRegistry` | function | the registry form of `createScopedImplement` — one contract registry, handlers still typed per endpoint scope |
+| `ScopedRegistryHandlers` | _type_ | scoped handler registry inferred from a contract registry |
+| `ScopedImplementationRegistry` | _type_ | contract registry whose every group scope is a key of the scope map |
+| `StreamScope` | _type_ | the scope `createScopedImplement(...).stream` accepts for one endpoint |
+| `ExactScopedRegistryHandlers` | _type_ | fail-first scoped registry shape that rejects extra registry and endpoint keys |
 | `implementRegistry` | function | bind one exact contract registry to one exact backend handler registry |
 | `createImplementRegistry` | function | context-typed factory for `implementRegistry` |
 | `ImplementationRegistry` | _type_ | flat literal registry of concrete contracts accepted by `implementRegistry` |
+| `KeyedServices` | _type_ | registry result: the mount-ordered `ServiceDef[]` carrying the same services under `.byKey` |
 | `RegistryHandlers` | _type_ | exact backend handler registry inferred from a contract registry |
 | `ExactRegistryHandlers` | _type_ | fail-first handler shape that rejects extra registry and endpoint keys |
 | `staticRoute` | function | a raw route that serves a directory |
@@ -6075,6 +6425,11 @@ Also re-exports the error helpers from `stitchkit/contract`.
 | `AuthHook` | _type_ | the hook `createAuthHook` returns |
 | `AuthHookConfig` | _type_ | config for `createAuthHook` |
 | `AuthRule` | _type_ | `'public' \| 'authenticated' \| predicate` |
+| `ScopedAuthRule` | _type_ | a rule plus its typed context contribution — `{ rule, inject? }` |
+| `AuthRules` | _type_ | the `rules` map: bare rules or scoped rules |
+| `RuleScopes` | _type_ | scope→context map derived from a `rules` object; `'public'` fields become optional |
+| `ScopedAuthHook` | _type_ | an auth hook carrying its derived scope map at the type level |
+| `AuthScopes` | _type_ | recover the derived map — `createScopedImplement<AuthScopes<typeof hook>>()` |
 | `BearerResolverConfig` | _type_ | config for `createBearerResolver` |
 | `JwtPayload` | _type_ | a decoded JWT payload |
 | `SignJwtOptions` | _type_ | options for `signJwt` (expiry, claims) |
@@ -6125,10 +6480,19 @@ Also re-exports the error helpers from `stitchkit/contract`.
 | `MultipartResult` | _type_ | what `parseMultipart` returns |
 | `parseMultipart` | function | parse a typed buffered/streaming multipart descriptor — [guide](../guide/server.md#multipart) |
 | `defineMultipartStream` | function | bind typed streaming file receivers and a final endpoint handler |
+| `createMultipartStream` | function | fix one handler context type for streaming multipart endpoints |
+| `MultipartStreamConfig` | _type_ | receivers plus the context-typed handler accepted by the streaming builders |
 | `MultipartFileMetadata` | _type_ | field, filename, declared media type and optional declared size |
 | `MultipartReceiver` | _type_ | consumer-owned Web-stream storage receiver |
 | `MultipartReceiverResult` | _type_ | receiver value plus rollback cleanup |
 | `StreamingMultipartImplementation` | _type_ | receiver registry and handler shape inferred by `defineMultipartStream` |
+| `bindProcessSignals` | function | bind `SIGINT` / `SIGTERM` to one managed `shutdown()` — one chain, force on a later signal, default disposition on the one after — [guide](../guide/testing-and-deployment.md#process-signals--bindprocesssignals) |
+| `ProcessSignalsOptions` | _type_ | config for `bindProcessSignals` |
+| `ProcessSignalsBinding` | _type_ | the `{ promise, close }` handle `bindProcessSignals` returns |
+| `ProcessSignalsErrorPhase` | _type_ | `'prepare' \| 'shutdown' \| 'complete'` — which phase an `onError` report came from |
+| `SignalSource` | _type_ | injectable signal source — `process` by default |
+| `ProcessSignalName` | _type_ | signal names the binding accepts (owned, so the published types need no `@types/node`) |
+| `ShutdownTarget` | _type_ | the `shutdown`-only slice a binding needs — an interface, so a [composite target](../guide/testing-and-deployment.md#composite-shutdown-target--parallel-domain-drains) can drain several domains under one signal machine |
 | `createRateLimiter` | function | token-bucket rate limiting — [guide](../guide/server.md#rate-limiting) |
 | `createCache` | function | an in-memory TTL cache |
 | `CacheOptions` | _type_ | bounded-cache options, including the maximum retained entry count |
@@ -6257,6 +6621,7 @@ payload.
 | `resolveMedia` | function | resolve a media reference for a tool result |
 | `validateMcpSchemas` | function | object-shaped assertion over the exact advertised schema surface — compatibility, typed properties and portable formats ([guide](../guide/mcp-and-agents.md#mcp-schema-validation-profile)) |
 | `listToolNames` | function | every contract/runtime tool name with origin, identity and transports — for stable snapshots — [guide](../guide/mcp-and-agents.md#pinning-tool-names--listtoolnames) |
+| `listContractToolNames` | function | the same listing straight from contracts — no handlers or stub services needed |
 | `McpHandlerConfig` | _type_ | server surface plus stateless HTTP transport config |
 | `McpHttpConfig` | _type_ | HTTP auth, protected-resource, legacy-era and security options |
 | `McpHttpHandler` | _type_ | framework-owned `{ fetch(request), close() }` lifecycle |
@@ -6434,7 +6799,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) |
-| `implement` / `createImplement` | function | bind a contract to typed handlers (same as `/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`) |
 | `NodeRuntimeServer` | _type_ | concrete `srvx/node` runtime escape hatch |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "stitchkit",
-  "version": "0.49.2",
+  "version": "0.51.0",
   "description": "Contract-first backend framework — one defineContract() into an HTTP API, MCP tools, AI-agent tools and a typed client. Bun and Node.",
   "keywords": [
     "bun",