@zhin.js/middleware 1.1.3 → 1.1.4

package/README.md

@@ -10,13 +10,24 @@ import { defineMiddleware } from 'zhin.js/middleware';
 
 export default defineMiddleware({
   phase: 'before-dispatch',
-  async handle(_context, next) { await next(); },
+  handle(_context, next) { return next(); },
 });
 ```
 
 Middleware 不直接持有 Root 或运行时 registry；每次执行使用同一 generation snapshot，
 更新时由 Feature Slot 原子替换。
 
+入站中间件可返回文本、JSX 或其他发送内容。`return next()` 保留下游的返回值与作者；
+`await next()` 后不返回也透传下游结果，返回新内容则替换待自动回复内容。不调用 `next()`
+会消费输入；不返回内容时不会自动回复。Runtime 在整条入站链回卷后只自动回复一次，
+显式调用 `input.$reply()` 仍可发送多条消息。已经发送的显式消息不会被返回值替换撤回。
+
+出站中间件使用 `target: 'outbound'`，通过 `input.replace(content)` 修改候选 payload，
+再调用 `next()` 放行；返回类型为 `void`，不参与入站的自动回复与 continuation 传递。
+
+`next()` 的 continuation 只用于透传，不暴露内容，也不可跨调用保存复用。每层只能调用
+一次 `next()`；遗漏 await 的下游操作仍会在当前 scope 结束前结算，异常向调用方传播。
+
 单文件插件可用 `setup({ addMiddleware })` 注册 `defineMiddleware(...)`；它仍参与
 统一 phase/order/topology 排序和 generation 回滚。
 

package/lib/continuation.d.ts

@@ -0,0 +1,6 @@
+/** Internal marker only; each frame additionally checks its exact carrier identity. */
+export declare const continuationBrand: unique symbol;
+/** Opaque result of `next()`. Return it to preserve the downstream author. */
+export interface MiddlewareContinuation {
+    readonly [continuationBrand]: never;
+}

package/lib/continuation.js

@@ -0,0 +1,2 @@
+/** Internal marker only; each frame additionally checks its exact carrier identity. */
+export const continuationBrand = Symbol('zhin.middleware-continuation');

package/lib/definition.d.ts

@@ -3,24 +3,33 @@
  * @module zhin.js/middleware
  */
 import type { AdapterClient, CapabilityContext, RegisteredAdapterName } from '@zhin.js/feature-kit';
+import type { MiddlewareContinuation } from './continuation.js';
+export type { MiddlewareContinuation } from './continuation.js';
 declare const middlewareBrand: "zhin.middleware/1";
 export type MiddlewarePhase = 'before-dispatch' | 'after-dispatch';
 export type MiddlewareTarget = 'inbound' | 'outbound';
-export type MiddlewareNext = () => Promise<void>;
+export type MiddlewareNext = () => Promise<MiddlewareContinuation>;
+export type OutboundMiddlewareNext = () => Promise<void>;
 export interface MiddlewareContext<TInput = unknown, TConfig = unknown, TAdapter extends string | undefined = undefined> extends CapabilityContext<TConfig> {
     readonly input: TInput;
     /** Lazily resolved native Client. Without `adapter`, its static type is `unknown`. */
     readonly $client: AdapterClient<TAdapter>;
 }
-export interface MiddlewareDefinition<TInput = unknown, TConfig = unknown, TAdapter extends string | undefined = string | undefined> {
+/** Shared metadata for the public inbound and outbound definition contracts. */
+export interface MiddlewareDefinitionBase<TAdapter extends string | undefined = string | undefined> {
     /** @internal Runtime feature brand. */
     readonly $feature: typeof middlewareBrand;
     readonly phase: MiddlewarePhase;
-    readonly target: MiddlewareTarget;
     readonly order: number;
     readonly adapter?: TAdapter;
-    handle(context: MiddlewareContext<TInput, TConfig, TAdapter>, next: MiddlewareNext): void | Promise<void>;
 }
+export type MiddlewareDefinition<TInput = unknown, TConfig = unknown, TAdapter extends string | undefined = string | undefined> = MiddlewareDefinitionBase<TAdapter> & ({
+    readonly target: 'inbound';
+    handle(context: MiddlewareContext<TInput, TConfig, TAdapter>, next: MiddlewareNext): unknown;
+} | {
+    readonly target: 'outbound';
+    handle(context: MiddlewareContext<TInput, TConfig, TAdapter>, next: OutboundMiddlewareNext): void | Promise<void>;
+});
 declare module '@zhin.js/plugin-runtime' {
     interface PluginSetupContext<TConfig = unknown> {
         addMiddleware<TInput = unknown>(localName: string, definition: MiddlewareDefinition<TInput, TConfig, string | undefined>): void;
@@ -32,19 +41,30 @@ declare module '@zhin.js/plugin-runtime' {
  *
  * @public
  */
-type MiddlewareAuthoringDefinition<TInput, TConfig> = (Omit<MiddlewareDefinition<TInput, TConfig, undefined>, '$feature' | 'phase' | 'target' | 'order'> & {
+type AuthoringForAdapter<TInput, TConfig, TAdapter extends string | undefined> = Omit<MiddlewareDefinitionBase<TAdapter>, '$feature' | 'phase' | 'order'> & {
     readonly phase?: MiddlewarePhase;
-    readonly target?: MiddlewareTarget;
     readonly order?: number;
-}) | {
-    [TAdapter in RegisteredAdapterName]: Omit<MiddlewareDefinition<TInput, TConfig, TAdapter>, '$feature' | 'phase' | 'target' | 'order'> & {
+} & ({
+    readonly target?: 'inbound';
+    handle(context: MiddlewareContext<TInput, TConfig, TAdapter>, next: MiddlewareNext): unknown;
+} | {
+    readonly target: 'outbound';
+    handle(context: MiddlewareContext<TInput, TConfig, TAdapter>, next: OutboundMiddlewareNext): void | Promise<void>;
+});
+type MiddlewareAuthoringDefinition<TInput, TConfig> = AuthoringForAdapter<TInput, TConfig, undefined> | {
+    [TAdapter in RegisteredAdapterName]: AuthoringForAdapter<TInput, TConfig, TAdapter> & {
         readonly adapter: TAdapter;
-        readonly phase?: MiddlewarePhase;
-        readonly target?: MiddlewareTarget;
-        readonly order?: number;
     };
 }[RegisteredAdapterName];
-export declare function defineMiddleware<TInput = unknown, TConfig = unknown>(definition: MiddlewareAuthoringDefinition<TInput, TConfig>): Readonly<MiddlewareDefinition<TInput, TConfig, string | undefined>>;
+export declare function defineMiddleware<TInput = unknown, TConfig = unknown>(definition: Extract<MiddlewareAuthoringDefinition<TInput, TConfig>, {
+    readonly target: 'outbound';
+}>): Readonly<Extract<MiddlewareDefinition<TInput, TConfig>, {
+    readonly target: 'outbound';
+}>>;
+export declare function defineMiddleware<TInput = unknown, TConfig = unknown>(definition: Extract<MiddlewareAuthoringDefinition<TInput, TConfig>, {
+    readonly target?: 'inbound';
+}>): Readonly<Extract<MiddlewareDefinition<TInput, TConfig>, {
+    readonly target: 'inbound';
+}>>;
 /** @internal Runtime validation for convention-discovered modules. */
 export declare function parseMiddlewareDefinition(value: unknown): MiddlewareDefinition;
-export {};

package/lib/middleware-index.d.ts

@@ -1,5 +1,14 @@
 import type { CapabilitySlot, PluginId, RuntimeSnapshot } from '@zhin.js/plugin-runtime';
-import type { MiddlewareDefinition, MiddlewareNext, MiddlewarePhase, MiddlewareTarget } from './definition.js';
+import type { MiddlewareDefinition, MiddlewarePhase, MiddlewareTarget, OutboundMiddlewareNext } from './definition.js';
+/** Transmission-neutral result policy supplied by the composition layer. */
+export interface MiddlewareResultPolicy<TResult> {
+    stop(owner: PluginId): TResult;
+    replace(owner: PluginId, value: unknown, downstream: TResult | undefined): TResult;
+}
+export interface MiddlewareRunResult {
+    readonly owner?: PluginId;
+    readonly value?: unknown;
+}
 export interface MiddlewareDescriptor {
     readonly owner: PluginId;
     readonly name: string;
@@ -15,6 +24,10 @@ export declare class MiddlewareIndex {
     readonly $projection: "zhin.middleware-index/1";
     constructor(slots: readonly Readonly<CapabilitySlot<MiddlewareDefinition>>[], snapshot: RuntimeSnapshot);
     list(): readonly MiddlewareDescriptor[];
-    run<TInput>(input: TInput, terminal?: MiddlewareNext, target?: MiddlewareTarget, operationSnapshot?: RuntimeSnapshot): Promise<void>;
+    run<TInput>(input: TInput, terminal?: OutboundMiddlewareNext, target?: 'inbound', operationSnapshot?: RuntimeSnapshot): Promise<MiddlewareRunResult>;
+    run<TInput>(input: TInput, terminal: OutboundMiddlewareNext | undefined, target: 'outbound', operationSnapshot?: RuntimeSnapshot): Promise<void>;
+    run<TInput>(input: TInput, terminal: OutboundMiddlewareNext | undefined, target: MiddlewareTarget, operationSnapshot?: RuntimeSnapshot): Promise<MiddlewareRunResult | void>;
+    /** Unwinds one inbound operation before its caller performs any automatic reply. */
+    runInbound<TInput, TResult>(input: TInput, terminal: () => Promise<TResult>, results: MiddlewareResultPolicy<TResult>, operationSnapshot?: RuntimeSnapshot): Promise<TResult>;
 }
 export declare function isMiddlewareIndex(value: unknown): value is MiddlewareIndex;

package/lib/middleware-index.js

@@ -1,4 +1,5 @@
-import { createCapabilityContext, operationClientAdapter, readOperationClient, } from '@zhin.js/feature-kit';
+import { createCapabilityContext, bindOperationInput, operationClientAdapter, readOperationClient, } from '@zhin.js/feature-kit';
+import { continuationBrand } from './continuation.js';
 export class MiddlewareIndex {
     snapshot;
     $projection = 'zhin.middleware-index/1';
@@ -21,6 +22,12 @@ export class MiddlewareIndex {
         return this.#records.map(({ slot: _slot, ...descriptor }) => descriptor);
     }
     async run(input, terminal = async () => undefined, target = 'inbound', operationSnapshot = this.snapshot) {
+        if (target === 'inbound') {
+            return this.runInbound(input, async () => { await terminal(); return {}; }, {
+                stop: (owner) => ({ owner }),
+                replace: (owner, value) => ({ owner, value }),
+            }, operationSnapshot);
+        }
         const clientAdapter = operationClientAdapter(input);
         const records = this.#records.filter((record) => record.target === target && (!record.adapter || record.adapter === clientAdapter));
         let cursor = -1;
@@ -31,19 +38,91 @@ export class MiddlewareIndex {
             const record = records[index];
             if (!record)
                 return terminal();
+            const authorInput = bindOperationInput(input, record.owner, operationSnapshot);
             const context = {
                 ...createCapabilityContext(operationSnapshot, record.owner),
-                input,
+                input: authorInput,
             };
             Object.defineProperty(context, '$client', {
                 enumerable: true,
-                get: () => readOperationClient(input, record.adapter),
+                get: () => readOperationClient(authorInput, record.adapter),
             });
             Object.freeze(context);
-            await record.slot.definition.handle(context, () => dispatch(index + 1));
+            const definition = record.slot.definition;
+            if (definition.target !== 'outbound')
+                throw new Error('Invalid outbound Middleware');
+            const result = await definition.handle(context, () => dispatch(index + 1));
+            if (result !== undefined)
+                throw new TypeError('Outbound Middleware must use input.replace(), not return content');
         };
         await dispatch(0);
     }
+    /** Unwinds one inbound operation before its caller performs any automatic reply. */
+    async runInbound(input, terminal, results, operationSnapshot = this.snapshot) {
+        const clientAdapter = operationClientAdapter(input);
+        const records = this.#records.filter((record) => record.target === 'inbound'
+            && (!record.adapter || record.adapter === clientAdapter));
+        const dispatch = async (index) => {
+            const record = records[index];
+            if (!record)
+                return terminal();
+            const definition = record.slot.definition;
+            if (definition.target !== 'inbound')
+                throw new Error('Invalid inbound Middleware');
+            const authorInput = bindOperationInput(input, record.owner, operationSnapshot);
+            const context = {
+                ...createCapabilityContext(operationSnapshot, record.owner), input: authorInput,
+            };
+            Object.defineProperty(context, '$client', {
+                enumerable: true, get: () => readOperationClient(authorInput, record.adapter),
+            });
+            Object.freeze(context);
+            let active = true;
+            let nextCalled = false;
+            let nextTask;
+            let carrier;
+            const next = () => {
+                if (!active)
+                    throw new Error('Middleware next() scope has ended');
+                if (nextCalled)
+                    throw new Error('Middleware next() called more than once');
+                nextCalled = true;
+                nextTask = dispatch(index + 1);
+                // Attach a rejection observer immediately even when an author forgets await.
+                void nextTask.catch(() => undefined);
+                const continuation = nextTask.then(() => {
+                    carrier = Object.freeze({ [continuationBrand]: undefined });
+                    return carrier;
+                });
+                void continuation.catch(() => undefined);
+                return continuation;
+            };
+            let returned;
+            try {
+                returned = await definition.handle(context, next);
+            }
+            catch (error) {
+                // Drain an admitted child before the owning generation lease can close.
+                await nextTask?.catch(() => undefined);
+                throw error;
+            }
+            finally {
+                active = false;
+            }
+            const downstream = nextTask ? await nextTask : undefined;
+            if (returned === undefined)
+                return nextTask ?? results.stop(record.owner);
+            if (returned && typeof returned === 'object' && continuationBrand in returned) {
+                if (returned !== carrier)
+                    throw new Error('Middleware continuation belongs to another frame or operation');
+                if (!nextTask)
+                    throw new Error('Middleware continuation has no downstream operation');
+                return nextTask;
+            }
+            return results.replace(record.owner, returned, downstream);
+        };
+        return dispatch(0);
+    }
 }
 export function isMiddlewareIndex(value) {
     return !!value && typeof value === 'object'

package/lib/provider.js

@@ -10,6 +10,7 @@ const middlewareFeature = defineFeatureProvider({
         setupMethod: 'addMiddleware',
         conventions: [directoryModules({
                 id: 'middlewares-index',
+                extensions: ['ts', 'tsx', 'js', 'mjs', 'cjs'],
                 layouts: [{ segments: ['middlewares', capture('name')], localName: (values) => captured(values, 'name') }],
             })],
         validate: parseMiddlewareDefinition,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhin.js/middleware",
-  "version": "1.1.3",
+  "version": "1.1.4",
   "description": "Convention-based Middleware Feature for Zhin Plugin Runtime",
   "type": "module",
   "main": "./lib/index.js",
@@ -17,8 +17,8 @@
     "src"
   ],
   "dependencies": {
-    "@zhin.js/feature-kit": "1.1.2",
-    "@zhin.js/plugin-runtime": "1.1.11"
+    "@zhin.js/feature-kit": "1.1.3",
+    "@zhin.js/plugin-runtime": "1.1.12"
   },
   "devDependencies": {
     "@types/node": "^26.1.2",

package/src/continuation.ts

@@ -0,0 +1,7 @@
+/** Internal marker only; each frame additionally checks its exact carrier identity. */
+export const continuationBrand: unique symbol = Symbol('zhin.middleware-continuation');
+
+/** Opaque result of `next()`. Return it to preserve the downstream author. */
+export interface MiddlewareContinuation {
+  readonly [continuationBrand]: never;
+}

package/src/definition.ts

@@ -7,12 +7,15 @@ import type {
   CapabilityContext,
   RegisteredAdapterName,
 } from '@zhin.js/feature-kit';
+import type { MiddlewareContinuation } from './continuation.js';
+export type { MiddlewareContinuation } from './continuation.js';
 
 const middlewareBrand = 'zhin.middleware/1' as const;
 
 export type MiddlewarePhase = 'before-dispatch' | 'after-dispatch';
 export type MiddlewareTarget = 'inbound' | 'outbound';
-export type MiddlewareNext = () => Promise<void>;
+export type MiddlewareNext = () => Promise<MiddlewareContinuation>;
+export type OutboundMiddlewareNext = () => Promise<void>;
 
 export interface MiddlewareContext<
   TInput = unknown,
@@ -25,23 +28,26 @@ export interface MiddlewareContext<
   readonly $client: AdapterClient<TAdapter>;
 }
 
-export interface MiddlewareDefinition<
-  TInput = unknown,
-  TConfig = unknown,
+/** Shared metadata for the public inbound and outbound definition contracts. */
+export interface MiddlewareDefinitionBase<
   TAdapter extends string | undefined = string | undefined,
 > {
   /** @internal Runtime feature brand. */
   readonly $feature: typeof middlewareBrand;
   readonly phase: MiddlewarePhase;
-  readonly target: MiddlewareTarget;
   readonly order: number;
   readonly adapter?: TAdapter;
-  handle(
-    context: MiddlewareContext<TInput, TConfig, TAdapter>,
-    next: MiddlewareNext,
-  ): void | Promise<void>;
 }
 
+export type MiddlewareDefinition<
+  TInput = unknown,
+  TConfig = unknown,
+  TAdapter extends string | undefined = string | undefined,
+> = MiddlewareDefinitionBase<TAdapter> & (
+  | { readonly target: 'inbound'; handle(context: MiddlewareContext<TInput, TConfig, TAdapter>, next: MiddlewareNext): unknown }
+  | { readonly target: 'outbound'; handle(context: MiddlewareContext<TInput, TConfig, TAdapter>, next: OutboundMiddlewareNext): void | Promise<void> }
+);
+
 declare module '@zhin.js/plugin-runtime' {
   interface PluginSetupContext<TConfig = unknown> {
     addMiddleware<TInput = unknown>(
@@ -57,27 +63,29 @@ declare module '@zhin.js/plugin-runtime' {
  *
  * @public
  */
+type AuthoringForAdapter<TInput, TConfig, TAdapter extends string | undefined> =
+  Omit<MiddlewareDefinitionBase<TAdapter>, '$feature' | 'phase' | 'order'> & {
+    readonly phase?: MiddlewarePhase;
+    readonly order?: number;
+  } & (
+    | { readonly target?: 'inbound'; handle(context: MiddlewareContext<TInput, TConfig, TAdapter>, next: MiddlewareNext): unknown }
+    | { readonly target: 'outbound'; handle(context: MiddlewareContext<TInput, TConfig, TAdapter>, next: OutboundMiddlewareNext): void | Promise<void> }
+  );
+
 type MiddlewareAuthoringDefinition<TInput, TConfig> =
-  | (Omit<
-      MiddlewareDefinition<TInput, TConfig, undefined>,
-      '$feature' | 'phase' | 'target' | 'order'
-    > & {
-      readonly phase?: MiddlewarePhase;
-      readonly target?: MiddlewareTarget;
-      readonly order?: number;
-    })
+  | AuthoringForAdapter<TInput, TConfig, undefined>
   | {
-      [TAdapter in RegisteredAdapterName]: Omit<
-        MiddlewareDefinition<TInput, TConfig, TAdapter>,
-        '$feature' | 'phase' | 'target' | 'order'
-      > & {
+      [TAdapter in RegisteredAdapterName]: AuthoringForAdapter<TInput, TConfig, TAdapter> & {
         readonly adapter: TAdapter;
-        readonly phase?: MiddlewarePhase;
-        readonly target?: MiddlewareTarget;
-        readonly order?: number;
       }
     }[RegisteredAdapterName];
 
+export function defineMiddleware<TInput = unknown, TConfig = unknown>(
+  definition: Extract<MiddlewareAuthoringDefinition<TInput, TConfig>, { readonly target: 'outbound' }>,
+): Readonly<Extract<MiddlewareDefinition<TInput, TConfig>, { readonly target: 'outbound' }>>;
+export function defineMiddleware<TInput = unknown, TConfig = unknown>(
+  definition: Extract<MiddlewareAuthoringDefinition<TInput, TConfig>, { readonly target?: 'inbound' }>,
+): Readonly<Extract<MiddlewareDefinition<TInput, TConfig>, { readonly target: 'inbound' }>>;
 export function defineMiddleware<TInput = unknown, TConfig = unknown>(
   definition: MiddlewareAuthoringDefinition<TInput, TConfig>,
 ): Readonly<MiddlewareDefinition<TInput, TConfig, string | undefined>> {

package/src/middleware-index.ts

@@ -1,16 +1,29 @@
 import type { CapabilitySlot, PluginId, RuntimeSnapshot } from '@zhin.js/plugin-runtime';
 import {
   createCapabilityContext,
+  bindOperationInput,
   operationClientAdapter,
   readOperationClient,
 } from '@zhin.js/feature-kit';
 import type {
   MiddlewareContext,
   MiddlewareDefinition,
-  MiddlewareNext,
   MiddlewarePhase,
   MiddlewareTarget,
+  OutboundMiddlewareNext,
 } from './definition.js';
+import { continuationBrand, type MiddlewareContinuation } from './continuation.js';
+
+/** Transmission-neutral result policy supplied by the composition layer. */
+export interface MiddlewareResultPolicy<TResult> {
+  stop(owner: PluginId): TResult;
+  replace(owner: PluginId, value: unknown, downstream: TResult | undefined): TResult;
+}
+
+export interface MiddlewareRunResult {
+  readonly owner?: PluginId;
+  readonly value?: unknown;
+}
 
 export interface MiddlewareDescriptor {
   readonly owner: PluginId;
@@ -51,12 +64,21 @@ export class MiddlewareIndex {
     return this.#records.map(({ slot: _slot, ...descriptor }) => descriptor);
   }
 
+  run<TInput>(input: TInput, terminal?: OutboundMiddlewareNext, target?: 'inbound', operationSnapshot?: RuntimeSnapshot): Promise<MiddlewareRunResult>;
+  run<TInput>(input: TInput, terminal: OutboundMiddlewareNext | undefined, target: 'outbound', operationSnapshot?: RuntimeSnapshot): Promise<void>;
+  run<TInput>(input: TInput, terminal: OutboundMiddlewareNext | undefined, target: MiddlewareTarget, operationSnapshot?: RuntimeSnapshot): Promise<MiddlewareRunResult | void>;
   async run<TInput>(
     input: TInput,
-    terminal: MiddlewareNext = async () => undefined,
+    terminal: OutboundMiddlewareNext = async () => undefined,
     target: MiddlewareTarget = 'inbound',
     operationSnapshot: RuntimeSnapshot = this.snapshot,
-  ): Promise<void> {
+  ): Promise<MiddlewareRunResult | void> {
+    if (target === 'inbound') {
+      return this.runInbound(input, async () => { await terminal(); return {}; }, {
+        stop: (owner) => ({ owner }),
+        replace: (owner, value) => ({ owner, value }),
+      }, operationSnapshot);
+    }
     const clientAdapter = operationClientAdapter(input);
     const records = this.#records.filter((record) =>
       record.target === target && (!record.adapter || record.adapter === clientAdapter));
@@ -66,19 +88,86 @@ export class MiddlewareIndex {
       cursor = index;
       const record = records[index];
       if (!record) return terminal();
+      const authorInput = bindOperationInput(input, record.owner, operationSnapshot);
       const context = {
         ...createCapabilityContext(operationSnapshot, record.owner),
-        input,
+        input: authorInput,
       } as MiddlewareContext<TInput>;
       Object.defineProperty(context, '$client', {
         enumerable: true,
-        get: () => readOperationClient(input, record.adapter),
+        get: () => readOperationClient(authorInput, record.adapter),
       });
       Object.freeze(context);
-      await record.slot.definition.handle(context, () => dispatch(index + 1));
+      const definition = record.slot.definition;
+      if (definition.target !== 'outbound') throw new Error('Invalid outbound Middleware');
+      const result = await definition.handle(context, () => dispatch(index + 1));
+      if (result !== undefined) throw new TypeError('Outbound Middleware must use input.replace(), not return content');
     };
     await dispatch(0);
   }
+
+  /** Unwinds one inbound operation before its caller performs any automatic reply. */
+  async runInbound<TInput, TResult>(
+    input: TInput,
+    terminal: () => Promise<TResult>,
+    results: MiddlewareResultPolicy<TResult>,
+    operationSnapshot: RuntimeSnapshot = this.snapshot,
+  ): Promise<TResult> {
+    const clientAdapter = operationClientAdapter(input);
+    const records = this.#records.filter((record) => record.target === 'inbound'
+      && (!record.adapter || record.adapter === clientAdapter));
+    const dispatch = async (index: number): Promise<TResult> => {
+      const record = records[index];
+      if (!record) return terminal();
+      const definition = record.slot.definition;
+      if (definition.target !== 'inbound') throw new Error('Invalid inbound Middleware');
+      const authorInput = bindOperationInput(input, record.owner, operationSnapshot);
+      const context = {
+        ...createCapabilityContext(operationSnapshot, record.owner), input: authorInput,
+      } as MiddlewareContext<TInput>;
+      Object.defineProperty(context, '$client', {
+        enumerable: true, get: () => readOperationClient(authorInput, record.adapter),
+      });
+      Object.freeze(context);
+      let active = true;
+      let nextCalled = false;
+      let nextTask: Promise<TResult> | undefined;
+      let carrier: MiddlewareContinuation | undefined;
+      const next = (): Promise<MiddlewareContinuation> => {
+        if (!active) throw new Error('Middleware next() scope has ended');
+        if (nextCalled) throw new Error('Middleware next() called more than once');
+        nextCalled = true;
+        nextTask = dispatch(index + 1);
+        // Attach a rejection observer immediately even when an author forgets await.
+        void nextTask.catch(() => undefined);
+        const continuation = nextTask.then(() => {
+          carrier = Object.freeze({ [continuationBrand]: undefined as never });
+          return carrier;
+        });
+        void continuation.catch(() => undefined);
+        return continuation;
+      };
+      let returned: unknown;
+      try {
+        returned = await definition.handle(context, next);
+      } catch (error) {
+        // Drain an admitted child before the owning generation lease can close.
+        await nextTask?.catch(() => undefined);
+        throw error;
+      } finally {
+        active = false;
+      }
+      const downstream = nextTask ? await nextTask : undefined;
+      if (returned === undefined) return nextTask ?? results.stop(record.owner);
+      if (returned && typeof returned === 'object' && continuationBrand in returned) {
+        if (returned !== carrier) throw new Error('Middleware continuation belongs to another frame or operation');
+        if (!nextTask) throw new Error('Middleware continuation has no downstream operation');
+        return nextTask;
+      }
+      return results.replace(record.owner, returned, downstream);
+    };
+    return dispatch(0);
+  }
 }
 
 export function isMiddlewareIndex(value: unknown): value is MiddlewareIndex {

package/src/provider.ts

@@ -12,6 +12,7 @@ const middlewareFeature = defineFeatureProvider({
     setupMethod: 'addMiddleware',
     conventions: [directoryModules({
       id: 'middlewares-index',
+      extensions: ['ts', 'tsx', 'js', 'mjs', 'cjs'],
       layouts: [{ segments: ['middlewares', capture('name')], localName: (values) => captured(values, 'name') }],
     })],
     validate: parseMiddlewareDefinition,