ts-procedures 10.1.1 → 10.2.0

package/build/stack-utils.test.js

@@ -0,0 +1,80 @@
+import { describe, expect, test } from 'vitest';
+import { captureDefinitionInfo, formatDefinitionInfo } from './stack-utils.js';
+describe('Stack Utils', () => {
+    describe('captureDefinitionInfo', () => {
+        test('returns definition info with definedAt', () => {
+            const info = captureDefinitionInfo();
+            // Should capture the call site in this test file
+            expect(info).toBeDefined();
+            expect(info.definitionStack).toBeDefined();
+            expect(typeof info.definitionStack).toBe('string');
+        });
+        test('definedAt contains file, line, column when available', () => {
+            const info = captureDefinitionInfo();
+            // The definedAt should be present since we're calling from user code (test file)
+            if (info.definedAt) {
+                expect(info.definedAt.file).toBeDefined();
+                expect(typeof info.definedAt.file).toBe('string');
+                expect(info.definedAt.line).toBeDefined();
+                expect(typeof info.definedAt.line).toBe('number');
+                expect(info.definedAt.line).toBeGreaterThan(0);
+                expect(info.definedAt.column).toBeDefined();
+                expect(typeof info.definedAt.column).toBe('number');
+                expect(info.definedAt.column).toBeGreaterThan(0);
+                expect(info.definedAt.raw).toBeDefined();
+                expect(typeof info.definedAt.raw).toBe('string');
+            }
+        });
+        test('definitionStack contains Error stack trace', () => {
+            const info = captureDefinitionInfo();
+            expect(info.definitionStack).toContain('Error');
+            expect(info.definitionStack).toContain('at ');
+        });
+    });
+    describe('formatDefinitionInfo', () => {
+        test('returns undefined when definedAt is not present', () => {
+            const info = {};
+            const result = formatDefinitionInfo(info, 'TestProcedure');
+            expect(result).toBeUndefined();
+        });
+        test('returns formatted string when definedAt is present', () => {
+            const info = {
+                definedAt: {
+                    file: '/app/procedures/test.ts',
+                    line: 42,
+                    column: 5,
+                    raw: 'at Object.<anonymous> (/app/procedures/test.ts:42:5)',
+                },
+            };
+            const result = formatDefinitionInfo(info, 'TestProcedure');
+            expect(result).toBeDefined();
+            expect(result).toContain('--- Procedure "TestProcedure" defined at ---');
+            expect(result).toContain('/app/procedures/test.ts:42:5');
+        });
+        test('includes procedure name in formatted output', () => {
+            const info = {
+                definedAt: {
+                    file: '/path/to/file.ts',
+                    line: 10,
+                    column: 3,
+                    raw: 'at /path/to/file.ts:10:3',
+                },
+            };
+            const result = formatDefinitionInfo(info, 'MyCustomProcedure');
+            expect(result).toContain('"MyCustomProcedure"');
+        });
+    });
+    describe('integration with procedure creation', () => {
+        test('captures location from calling code', () => {
+            // Helper to simulate what happens in Create()
+            function simulateCreate() {
+                return captureDefinitionInfo();
+            }
+            const info = simulateCreate();
+            // Should have captured the location of the simulateCreate() call
+            expect(info).toBeDefined();
+            expect(info.definitionStack).toBeDefined();
+        });
+    });
+});
+//# sourceMappingURL=stack-utils.test.js.map

package/build/stack-utils.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stack-utils.test.js","sourceRoot":"","sources":["../src/stack-utils.test.ts"],"names":[],"mappings":"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"}

package/docs/core.md

@@ -14,6 +14,7 @@ Procedures<TContext, TExtendedConfig>(options?: {
     schema?: { adapters?: SchemaAdapter[] }
     http?: { pathPrefix?: string; scope?: string }
     onCreate?: (procedure: AnyProcedureRegistration<TContext, TExtendedConfig>) => void
+    middleware?: FactoryMiddleware<TContext>[]   // runs with final ctx + input for all procedures
 })
 ```
 
@@ -25,9 +26,12 @@ Procedures<TContext, TExtendedConfig>(options?: {
 | `options.schema.adapters` | Plug in additional schema libraries via the `SchemaAdapter` interface. TypeBox is built in. See [Other Schema Libraries](#other-schema-libraries--schemaadapter). |
 | `options.http` | Factory-level defaults for `CreateHttp` / `CreateHttpStream`: `pathPrefix` is prepended to every route's `path` at registration time (part of the route's identity, unlike a server builder's mount prefix), and `scope` is the default codegen scope for routes that don't set one. Per-route config always wins. |
 | `options.onCreate` | Optional callback invoked when each procedure is registered (runtime)      |
+| `options.middleware` | Array of middleware functions that run for every procedure on this factory. They receive the final resolved `ctx` (your `TContext` + `error()` + `signal`) plus the validated input, and can inspect ("parse the incoming call"), augment via `next({ ctx?, input? })`, or short-circuit. See `FactoryMiddleware`. |
 
 **Returns:** `Create`, `CreateStream`, `CreateHttp`, `CreateHttpStream`, plus introspection helpers `getProcedures()`, `getProcedure(name)`, `removeProcedure(name)`, and `clear()`.
 
+Factory `middleware` runs with the resolved context + input for every procedure defined through the factory (transport-independent, useful for authorization that needs `ctx` + call data). Builder-level middleware lives on `HonoAppBuilder` (see [HTTP Integrations](./http-integrations.md)).
+
 ## Create Function
 
 The `Create` function defines individual procedures:
@@ -74,6 +78,7 @@ const { UpdateUser } = CreateHttp(
 **Rules:**
 - `schema.req` and `schema.params` are **mutually exclusive** — `schema.params` belongs to RPC procedures (`Create`/`CreateStream`), `schema.req` to HTTP procedures. Using `schema.params` on `CreateHttp` throws `ProcedureRegistrationError`.
 - Valid channels are `pathParams`, `query`, `body`, and `headers`; each is validated independently with per-channel error messages.
+- The channel names are provided by `THttpReqInput` (and its alias `APIInput` from `ts-procedures/http`) so that IDEs offer autocomplete when writing `schema: { req: { ... } }`. Use `satisfies APIInput` for additional typo protection on the keys.
 - `schema.res.body` documents the response body (drives codegen); omit `schema.res` entirely for 204-style no-content routes.
 - Factory-level `http.pathPrefix` / `http.scope` defaults apply; per-route config wins.
 - For HTTP streaming routes, use `CreateHttpStream` — same `schema.req` channels plus `schema.yield`.
@@ -500,6 +505,7 @@ Creates a procedure factory.
 - `options.schema.adapters` - Additional schema-library adapters (see [Other Schema Libraries](#other-schema-libraries--schemaadapter))
 - `options.http` - Factory-level `pathPrefix` / `scope` defaults for `CreateHttp` / `CreateHttpStream`
 - `options.onCreate` - Callback invoked when each procedure is registered
+- `options.middleware` - Factory-level middleware with access to final `ctx` + input (for authz, enrichment, call parsing, etc.)
 
 **Returns:**
 - `Create` / `CreateStream` / `CreateHttp` / `CreateHttpStream` - Functions to define procedures
@@ -560,6 +566,8 @@ import type {
   TNoContextProvided,
   HttpMethod,
   HttpReturn,
+  FactoryMiddleware,                // for Procedures({ middleware }) — receives final ctx + input
+
 
   // Errors
   ProcedureErrorKind,               // 'procedure' | 'validation' | 'yield-validation' | 'registration'

package/docs/http-integrations.md

@@ -219,6 +219,46 @@ new HonoAppBuilder({
 
 The observer is awaited before the response is sent, and any error it throws is swallowed (logged to the console) so a broken instrumentation hook can't corrupt the primary flow.
 
+### Middleware (auth, tenancy, guards)
+
+Middleware can be declared at two levels that compose naturally.
+
+**At the `HonoAppBuilder` (serving / transport level):**
+
+- `new HonoAppBuilder({ middleware: [mw, ...] })`
+- `builder.use(mw)` or `builder.use('/specific/*', mw)` (chainable)
+- Per registration: `.register(factory, ctx, { middleware: [mw], context?: extraLayer })`
+
+Signature: `(c: Context, next) => Response | Promise<Response|void> | void`.
+
+**At the `Procedures()` factory (definition / business-logic level):**
+
+```ts
+const Protected = Procedures<MyCtx>({
+  middleware: [({ ctx, input, next }) => { ... }]
+})
+```
+
+These run *after* context resolution but before your handler. They receive the final `ctx` (same one the handler sees) + the validated `input`, so you can "parse the incoming call", perform authz using `ctx.user` + `input`, or augment via `next({ ctx?, input? })`. Defined as `FactoryMiddleware<TContext>`.
+
+See the `Procedures()` options in [Core](./core.md).
+
+Use builder middleware for raw request concerns and factory middleware for ctx-aware logic. Errors from either flow through your taxonomy / `onError`.
+
+The builder example below shows the two layers working together:
+
+```ts
+const app = new HonoAppBuilder({ pathPrefix: '/api', middleware: [authenticate] })
+  .register(Protected, (c) => ({
+    tenant: c.get('tenant'),
+    user: getUser(c),
+  }))
+  .register(Public, (c) => ({ requestId: c.req.header('x-rid') }))
+  .build()
+```
+
+`context` layers (via `register(..., { context })` or arrays) are resolved left-to-right via `composeContextInits`. Middleware declared at either level flows errors through `onRequestError` → taxonomy → `onError`.
+
 ### Dispatch order inside each builder's catch block
 
 1. **`onRequestError`** (observer) — awaited, can't alter dispatch or response
@@ -311,33 +351,7 @@ const docs = new DocRegistry({ errors: appErrors, basePath: '/api' })
 
 `http-stream` route docs include the route's `yield` and `res.headers` schemas. (Through v8, live envelopes silently dropped these for `http-stream` routes, so generated clients lost those types unless the envelope was hand-authored; v9 fixed this.)
 
-### Envelope versioning
-
-Every envelope carries two top-level metadata fields so downstream consumers (docs viewers, codegen, dashboards) can reason about format compatibility:
-
-```jsonc
-{
-  "specVersion": 1,             // wire-format version of the envelope itself
-  "generatorVersion": "10.0.0", // ts-procedures package version that produced it
-  "basePath": "/api",
-  "headers": [],
-  "errors": [ /* ... */ ],
-  "routes": [ /* ... */ ]
-}
-```
-
-- **`specVersion`** is a small monotonic integer, bumped **only** when the envelope shape changes in a way parsers must react to — never on ordinary package releases. Branch on it. An envelope with no `specVersion` predates the field and must be treated as `1`. The current value is exported as `DOC_ENVELOPE_SPEC_VERSION` from `ts-procedures` and `ts-procedures/server`.
-- **`generatorVersion`** is the producing package version (`DOC_ENVELOPE_GENERATOR_VERSION`, exported from `ts-procedures/server`). It is informational only — for telemetry and "which release served this?" — and must **not** drive parse-compatibility decisions, since it churns on every release regardless of the envelope format.
-
-If you'd rather not advertise the exact package version on a public docs endpoint, strip it with the `transform` hook:
-
-```typescript
-app.get('/docs', (c) => c.json(
-  builder.toDocEnvelope({ transform: ({ generatorVersion, ...env }) => env }),
-))
-```
-
-The `DocRegistry` output is the input for [Client Code Generation](./client-and-codegen.md). Building a third-party docs viewer or other tool that consumes the served envelope? The full wire contract — every field, per-kind shapes, and a validatable JSON Schema — is in [DocEnvelope Spec](./doc-envelope-spec-v1.md) (`doc-envelope-v1.schema.json`).
+The `DocRegistry` output is the input for [Client Code Generation](./client-and-codegen.md).
 
 ## Type Exports
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ts-procedures",
-  "version": "10.1.1",
+  "version": "10.2.0",
   "description": "A TypeScript RPC framework that creates type-safe, schema-validated procedure calls with a single function definition. Define your procedures once and get full type inference, runtime validation, and framework integration hooks.",
   "main": "build/exports.js",
   "types": "build/exports.d.ts",
@@ -76,15 +76,15 @@
     "typebox": "^1.0.30"
   },
   "devDependencies": {
-    "@eslint/js": "^10.0.1",
-    "@typescript-eslint/eslint-plugin": "^8.53.0",
-    "@typescript-eslint/parser": "^8.53.0",
-    "astro": "^7.0.2",
-    "eslint": "^10.5.0",
-    "globals": "^17.7.0",
+    "@eslint/js": "^9.17.0",
+    "astro": "^6.3.1",
+    "eslint": "^9.17.0",
+    "globals": "^15.0.0",
     "hono": "^4.7.4",
-    "typescript": "^6.0.3",
+    "typescript": "^5.7.0",
     "typescript-eslint": "^8.53.0",
+    "@typescript-eslint/eslint-plugin": "^8.53.0",
+    "@typescript-eslint/parser": "^8.53.0",
     "vitest": "^4.0.18"
   }
 }

package/src/adapters/astro/README.md

@@ -86,3 +86,5 @@ Dispatch rules:
 ## What's NOT included
 
 - DocRegistry coupling — wire `DocRegistry` against the same builders separately for client codegen.
+
+Middleware, guards, and context layering are configured on the `HonoAppBuilder` instances you pass in (`.use()`, `middleware`, per-`register` options). The Astro adapter just dispatches the pre-built apps.

package/src/adapters/hono/envelope-parity.test.ts

@@ -3,10 +3,8 @@ import { dirname, resolve } from 'node:path'
 import { fileURLToPath } from 'node:url'
 import { describe, expect, it } from 'vitest'
 import { Type } from 'typebox'
-import pkg from '../../../package.json' with { type: 'json' }
 import { Procedures } from '../../core/procedures.js'
 import { HonoAppBuilder, defineErrorTaxonomy } from './index.js'
-import { DOC_ENVELOPE_SPEC_VERSION } from '../../server/spec-version.js'
 import type { RPCConfig } from '../../server/types.js'
 
 /**
@@ -18,15 +16,12 @@ import type { RPCConfig } from '../../server/types.js'
  * The envelope is codegen's input; if this test fails, generated client output
  * WILL drift.
  *
- * TWO documented deviations from the raw v8 capture:
- *   1. v8's CreateHttpStream dropped the `yield` schema (and `res.headers`) from
- *      http-stream route docs — the registration stored `yieldType` while the
- *      doc builder read `yield`. v9 fixes that, so the fixture's TailUser route
- *      was patched to include the `yield` schema the builder now emits.
- *   2. v9 adds envelope-level `specVersion`/`generatorVersion` metadata that v8
- *      never emitted. These are asserted explicitly below, then stripped before
- *      the deep-equal so the rest stays byte-for-byte with the v8 capture.
- * Everything else is the untouched v8 capture.
+ * ONE documented deviation from the raw v8 capture: v8's CreateHttpStream
+ * dropped the `yield` schema (and `res.headers`) from http-stream route docs —
+ * the registration stored `yieldType` while the doc builder read `yield`. v9
+ * fixes that, so the fixture's TailUser route was patched to include the
+ * `yield` schema the builder now (correctly) emits. Everything else is the
+ * untouched v8 capture.
  */
 class TeapotError extends Error {}
 
@@ -126,13 +121,6 @@ describe('DocEnvelope parity with v8.6.0', () => {
     const expected = JSON.parse(await readFile(fixturePath, 'utf-8'))
     const actual = JSON.parse(JSON.stringify(builder.toDocEnvelope()))
 
-    // Deviation #2: assert the new v9 envelope metadata, then strip it so the
-    // remaining shape matches the untouched v8 capture.
-    expect(actual.specVersion).toBe(DOC_ENVELOPE_SPEC_VERSION)
-    expect(actual.generatorVersion).toBe(pkg.version)
-    delete actual.specVersion
-    delete actual.generatorVersion
-
     expect(actual).toEqual(expected)
   })
 })

package/src/adapters/hono/handlers/http-stream.ts

@@ -7,9 +7,9 @@ import { resolveFactoryContext } from '../../../server/context.js'
 import { extractReqChannels } from '../../../server/request/params.js'
 import { parseQueryNative } from '../../../server/request/query.js'
 import { SseEventSequencer } from '../../../server/sse.js'
-import { honoRequestSource, respondToDispatch } from '../request.js'
+import { honoRequestSource, respondToDispatch, runMiddlewareList } from '../request.js'
 import { midStreamErrorConfig, preStreamErrorConfig } from '../types.js'
-import type { DocAccumulator, HonoAppBuilderConfig, HonoFactoryItem } from '../types.js'
+import type { DocAccumulator, HonoAppBuilderConfig, HonoFactoryItem, HonoRequestMiddleware } from '../types.js'
 
 export function installHttpStreamRoute(params: {
   app: Hono
@@ -17,8 +17,9 @@ export function installHttpStreamRoute(params: {
   factoryItem: HonoFactoryItem
   cfg: HonoAppBuilderConfig
   docs: DocAccumulator
+  builderMiddleware?: HonoRequestMiddleware[]
 }): void {
-  const { app, procedure, factoryItem, cfg, docs } = params
+  const { app, procedure, factoryItem, cfg, docs, builderMiddleware } = params
   const queryParser = cfg.api?.queryParser ?? parseQueryNative
 
   const route = buildHttpStreamRouteDoc(procedure, cfg.pathPrefix, factoryItem.extendProcedureDoc as any)
@@ -26,8 +27,16 @@ export function installHttpStreamRoute(params: {
 
   const reqSchema = procedure.config.schema?.req
 
+  const combinedMw = [
+    ...(builderMiddleware ?? []),
+    ...(factoryItem.middleware ?? []),
+  ]
+
   app.on(procedure.config.method.toUpperCase(), route.fullPath, async (c: Context) => {
     try {
+      const early = await runMiddlewareList(c, combinedMw)
+      if (early) return early
+
       const context = await resolveFactoryContext(factoryItem.factoryContext, c)
 
       const reqParams = reqSchema

package/src/adapters/hono/handlers/http.ts

@@ -5,9 +5,9 @@ import { buildHttpRouteDoc } from '../../../server/docs/http-doc.js'
 import { resolveFactoryContext } from '../../../server/context.js'
 import { defaultSuccessStatus, extractReqChannels } from '../../../server/request/params.js'
 import { parseQueryNative } from '../../../server/request/query.js'
-import { honoRequestSource, respondToDispatch } from '../request.js'
+import { honoRequestSource, respondToDispatch, runMiddlewareList } from '../request.js'
 import { preStreamErrorConfig } from '../types.js'
-import type { DocAccumulator, HonoAppBuilderConfig, HonoFactoryItem } from '../types.js'
+import type { DocAccumulator, HonoAppBuilderConfig, HonoFactoryItem, HonoRequestMiddleware } from '../types.js'
 
 export function installHttpRoute(params: {
   app: Hono
@@ -15,8 +15,9 @@ export function installHttpRoute(params: {
   factoryItem: HonoFactoryItem
   cfg: HonoAppBuilderConfig
   docs: DocAccumulator
+  builderMiddleware?: HonoRequestMiddleware[]
 }): void {
-  const { app, procedure, factoryItem, cfg, docs } = params
+  const { app, procedure, factoryItem, cfg, docs, builderMiddleware } = params
   const queryParser = cfg.api?.queryParser ?? parseQueryNative
 
   const route = buildHttpRouteDoc(procedure, cfg.pathPrefix, factoryItem.extendProcedureDoc as any)
@@ -25,8 +26,16 @@ export function installHttpRoute(params: {
   const successStatus = procedure.config.successStatus ?? defaultSuccessStatus(procedure.config.method)
   const reqSchema = procedure.config.schema?.req
 
+  const combinedMw = [
+    ...(builderMiddleware ?? []),
+    ...(factoryItem.middleware ?? []),
+  ]
+
   app.on(procedure.config.method.toUpperCase(), route.fullPath, async (c: Context) => {
     try {
+      const early = await runMiddlewareList(c, combinedMw)
+      if (early) return early
+
       const context = await resolveFactoryContext(factoryItem.factoryContext, c)
 
       const reqParams = reqSchema

package/src/adapters/hono/handlers/rpc.ts

@@ -4,9 +4,9 @@ import type { RPCConfig } from '../../../server/types.js'
 import { dispatchPreStreamError } from '../../../server/errors/dispatch.js'
 import { buildRpcRouteDoc } from '../../../server/docs/rpc-doc.js'
 import { resolveFactoryContext } from '../../../server/context.js'
-import { respondToDispatch } from '../request.js'
+import { respondToDispatch, runMiddlewareList } from '../request.js'
 import { preStreamErrorConfig } from '../types.js'
-import type { DocAccumulator, HonoAppBuilderConfig, HonoFactoryItem } from '../types.js'
+import type { DocAccumulator, HonoAppBuilderConfig, HonoFactoryItem, HonoRequestMiddleware } from '../types.js'
 
 export function installRpcRoute(params: {
   app: Hono
@@ -14,14 +14,23 @@ export function installRpcRoute(params: {
   factoryItem: HonoFactoryItem
   cfg: HonoAppBuilderConfig
   docs: DocAccumulator
+  builderMiddleware?: HonoRequestMiddleware[]
 }): void {
-  const { app, procedure, factoryItem, cfg, docs } = params
+  const { app, procedure, factoryItem, cfg, docs, builderMiddleware } = params
 
   const route = buildRpcRouteDoc(procedure, cfg.pathPrefix, factoryItem.extendProcedureDoc as any)
   docs.push(route)
 
+  const combinedMw = [
+    ...(builderMiddleware ?? []),
+    ...(factoryItem.middleware ?? []),
+  ]
+
   app.post(route.path, async (c: Context) => {
     try {
+      const early = await runMiddlewareList(c, combinedMw)
+      if (early) return early
+
       const context = await resolveFactoryContext(factoryItem.factoryContext, c)
       const body = await c.req.json().catch(() => ({}))
       const result = await procedure.handler({ ...context, signal: c.req.raw.signal }, body)

package/src/adapters/hono/handlers/stream.ts

@@ -7,9 +7,9 @@ import { dispatchMidStreamError, dispatchPreStreamError } from '../../../server/
 import { buildStreamRouteDoc } from '../../../server/docs/stream-doc.js'
 import { resolveFactoryContext } from '../../../server/context.js'
 import { SseEventSequencer } from '../../../server/sse.js'
-import { respondToDispatch } from '../request.js'
+import { respondToDispatch, runMiddlewareList } from '../request.js'
 import { midStreamErrorConfig, preStreamErrorConfig } from '../types.js'
-import type { DocAccumulator, HonoAppBuilderConfig, HonoFactoryItem } from '../types.js'
+import type { DocAccumulator, HonoAppBuilderConfig, HonoFactoryItem, HonoRequestMiddleware } from '../types.js'
 
 export function installRpcStreamRoute(params: {
   app: Hono
@@ -18,8 +18,9 @@ export function installRpcStreamRoute(params: {
   cfg: HonoAppBuilderConfig
   docs: DocAccumulator
   streamMode: StreamMode
+  builderMiddleware?: HonoRequestMiddleware[]
 }): void {
-  const { app, procedure, factoryItem, cfg, docs, streamMode } = params
+  const { app, procedure, factoryItem, cfg, docs, streamMode, builderMiddleware } = params
 
   const route = buildStreamRouteDoc(
     procedure,
@@ -29,8 +30,16 @@ export function installRpcStreamRoute(params: {
   )
   docs.push(route)
 
+  const combinedMw = [
+    ...(builderMiddleware ?? []),
+    ...(factoryItem.middleware ?? []),
+  ]
+
   const handler = async (c: Context) => {
     try {
+      const early = await runMiddlewareList(c, combinedMw)
+      if (early) return early
+
       const context = await resolveFactoryContext(factoryItem.factoryContext, c)
 
       const reqParams =

package/src/adapters/hono/index.test.ts

@@ -325,3 +325,73 @@ describe('HonoAppBuilder — per-factory streamMode override', () => {
     await res.text()
   })
 })
+
+describe('HonoAppBuilder — middleware (new)', () => {
+  test('builder config.middleware and per-register middleware both run; register ones after builder ones', async () => {
+    const order: string[] = []
+    const builderMw = vi.fn(async (_c: any, next: any) => { order.push('builder'); await next() })
+    const regMw = vi.fn(async (_c: any, next: any) => { order.push('register'); await next() })
+
+    const P = Procedures<object, RPCConfig>()
+    P.Create('Ping', { scope: 'p', version: 1 }, async () => ({ ok: true }))
+
+    const app = new HonoAppBuilder({ middleware: [builderMw] })
+      .register(P, () => ({}), { middleware: [regMw] })
+      .build()
+
+    const res = await app.request('/p/ping/1', { method: 'POST', body: '{}', headers: { 'Content-Type': 'application/json' } })
+    expect(res.status).toBe(200)
+    expect(order).toEqual(['builder', 'register'])
+  })
+
+  test('middleware can short-circuit by throwing (flows to dispatch + onRequestError)', async () => {
+    const onRequestError = vi.fn()
+    const P = Procedures<object, RPCConfig>()
+    P.Create('Secret', { scope: 's', version: 1 }, async () => ({ secret: true }))
+
+    const app = new HonoAppBuilder({ onRequestError })
+      .register(P, () => ({}), {
+        middleware: [async () => { throw Object.assign(new Error('nope'), { status: 401 }) }],
+      })
+      .build()
+
+    const res = await app.request('/s/secret/1', { method: 'POST', body: '{}', headers: { 'Content-Type': 'application/json' } })
+    expect(res.status).toBe(500) // default path since no taxonomy matched the thrown Error
+    expect(onRequestError).toHaveBeenCalledTimes(1)
+  })
+
+  test('register options.context layers are composed with main factoryContext (later wins)', async () => {
+    const P = Procedures<{ tenant?: string; uid: string }, RPCConfig>()
+    P.Create('WhoAmI', { scope: 'w', version: 1 }, async (ctx) => ({ tenant: ctx.tenant, uid: ctx.uid }))
+
+    const base = (c: any) => ({ uid: c.req.header('x-uid') || 'u0' })
+    const tenantLayer = { tenant: 't-from-layer' }
+
+    const app = new HonoAppBuilder()
+      .register(P, base, { context: tenantLayer as any })
+      .build()
+
+    const res = await app.request('/w/who-am-i/1', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json', 'x-uid': 'user-xyz' },
+      body: '{}',
+    })
+    expect(await res.json()).toEqual({ tenant: 't-from-layer', uid: 'user-xyz' })
+  })
+
+  test('chainable .use() installs and runs for procedures', async () => {
+    const calls: string[] = []
+    const mw = async (_c: any, next: any) => { calls.push('used'); await next() }
+
+    const P = Procedures<object, RPCConfig>()
+    P.Create('X', { scope: 'x', version: 1 }, async () => ({}))
+
+    const b = new HonoAppBuilder()
+    b.use(mw)
+    b.register(P, () => ({}))
+    const app = b.build()
+
+    await app.request('/x/x/1', { method: 'POST', body: '{}', headers: { 'Content-Type': 'application/json' } })
+    expect(calls).toContain('used')
+  })
+})