stitchkit 0.49.1 → 0.50.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,74 @@ 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 that claim (→ ADR 0075).
+- 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
@@ -974,9 +1057,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 +3663,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' }, {
@@ -3870,36 +3957,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
@@ -4612,8 +4720,9 @@ expect(res.status).toBe(404)
 expect(await res.json()).toEqual({ error: { code: 'NOT_FOUND', message: 'Note not found' } })
 ```
 
-stitchkit's own suite — 143 tests in `packages/core/tests` — is the working
-reference for testing each piece.
+The suite in `packages/core/tests` is the working reference for testing each
+piece. Its size changes with the public surface, so the guide does not pin a
+count that can drift independently from the test runner.
 
 ## Deployment
 
@@ -4636,34 +4745,58 @@ 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.on('SIGTERM', () => void shutdown())
-process.on('SIGINT', () => void shutdown())
+    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`.
+
 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
@@ -4796,10 +4929,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
 
@@ -4989,6 +5132,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`
@@ -5918,13 +6124,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) |
@@ -5974,7 +6181,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 |
@@ -6010,6 +6217,15 @@ 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` |
@@ -6124,10 +6340,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 of a managed handle a binding needs |
 | `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 |
@@ -6433,7 +6658,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.1",
+  "version": "0.50.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",