@hile/model 2.0.0

package/README.md

@@ -0,0 +1,194 @@
+# @hile/model
+
+定义和调用业务模型（model），支持 services 依赖注入和中间件 pipeline。
+
+## 它解决什么问题？
+
+应用中的业务逻辑如果散落在 API 控制器、页面组件和服务中，会变得难以测试和复用。`@hile/model` 提供一个统一的层来封装领域逻辑：
+
+- **业务逻辑集中**：每个模型文件包含一个 `defineModel`，业务逻辑不再散落
+- **可选依赖注入**：支持声明 services 依赖，自动 `loadService` 后透传给 main 函数
+- **中间件 pipeline**：支持 Koa 风格中间件链，可在业务逻辑前后执行横切关注点（日志、鉴权、事务等）
+- **与服务容器解耦**：不同于 `@hile/core` 的容器单例，每次 `loadModel` 都重新执行 `main`，适合请求级别的上下文
+
+## 安装
+
+```bash
+pnpm add @hile/model
+```
+
+依赖 `@hile/core`（workspace peer dependency）。
+
+## 快速开始
+
+```typescript
+import { defineModel, loadModel } from '@hile/model'
+
+const greetModel = defineModel(async (input: { name: string }) => {
+  return `Hello, ${input.name}!`
+})
+
+const result = await loadModel(greetModel, { name: 'World' })
+console.log(result) // Hello, World!
+```
+
+## 使用指南
+
+### 基础模型（无 services）
+
+一个输入、一个输出：
+
+```typescript
+// src/models/greet.model.ts
+import { defineModel } from '@hile/model'
+export default defineModel(async (input: { name: string }) => {
+  return { greeting: `Hello, ${input.name}!` }
+})
+```
+
+```typescript
+// 消费
+import { loadModel } from '@hile/model'
+import greetModel from '@/models/greet.model'
+
+const result = await loadModel(greetModel, { name: 'World' })
+```
+
+### 注入 services
+
+通过 `services` 声明依赖，`main` 的第一个参数是加载后的 services 实例元组：
+
+```typescript
+import { defineModel } from '@hile/model'
+import { defineService } from '@hile/core'
+
+const userService = defineService('user', async () => ({
+  findById: async (id: number) => ({ id, name: 'Alice' }),
+}))
+
+const getUserModel = defineModel({
+  services: [userService],
+  async main([user], input: { id: number }) {
+    return user.findById(input.id)
+  },
+})
+```
+
+services 数组与 main 首参元组顺序一致。
+
+### 中间件 pipeline
+
+Koa 风格中间件链，在 `main` 前后执行横切逻辑：
+
+```typescript
+import { defineModel, type PipelineMiddleware } from '@hile/model'
+
+const logger: PipelineMiddleware = async (ctx, next) => {
+  console.log('before:', ctx.args)
+  await next()
+  console.log('after')
+}
+
+const model = defineModel({
+  pipelines: [logger],
+  async main(input: { id: number }) {
+    return fetchUser(input.id)
+  },
+})
+```
+
+中间件特性：
+
+- 通过 `ctx.args` 改写入参
+- 通过 `ctx.state` 在中间件间传递数据
+- 不调 `next()` 可短路，`main` 不会执行
+- 最后一个中间件不应调 `next()`
+
+### 函数简写
+
+无 services 和 pipelines 时可直接传入 `main`：
+
+```typescript
+const model = defineModel(async (input: { id: number }) => input.id)
+// 等价于
+const model = defineModel({ main: async (input: { id: number }) => input.id })
+```
+
+## API 参考
+
+### 顶层导出
+
+| 导出 | 说明 |
+|------|------|
+| `defineModel` | 定义业务模型 |
+| `loadModel` | 执行模型，返回 `Promise<R>` |
+| `isModel` | 校验对象是否合法 `ModelDefinition` |
+| `Pipeline` | pipeline 类 |
+| `PipelineContext` | pipeline 上下文 |
+| `ModelDefinition` | 模型类型 |
+| `ModelProps` | `defineModel` 入参类型 |
+| `ModelFlag` | 模型内部标记类型 |
+| `PipelineMiddleware` | 中间件类型 |
+| `ModelPipeline` | pipeline 中间件列表类型 |
+| `InferServiceResult` | 从 `ServiceRegisterProps` 推断服务实例类型 |
+| `InferredServices` | services 元组 → 实例元组类型 |
+
+### defineModel
+
+```typescript
+// 简写形式
+defineModel<TInput extends object, R>(
+  main: (input: TInput) => R | Promise<R>,
+): ModelDefinition<TInput, R>
+
+// 完整形式
+defineModel<S, TInput, R>(
+  options: ModelProps<S, TInput, R>,
+): ModelDefinition<TInput, R>
+```
+
+### ModelProps
+
+| 属性 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `main` | `function` | 是 | 业务函数。有 services 时首参为实例元组，次参为 input；否则仅 input |
+| `services` | `ServiceRegisterProps[]` | 否 | 依赖的服务列表，自动 `loadService` |
+| `pipelines` | `PipelineMiddleware[]` | 否 | Koa 风格中间件列表 |
+
+### ModelDefinition
+
+```typescript
+interface ModelDefinition<TInput extends object, R> {
+  readonly flag: symbol
+  readonly handler: (input: TInput) => Promise<R>
+}
+```
+
+### loadModel
+
+```typescript
+loadModel<TInput extends object, R>(
+  model: ModelDefinition<TInput, R>,
+  input: TInput,
+): Promise<R>
+```
+
+非容器单例，每次调用都重新执行 `main`。首参非 `defineModel` 返回值时抛 `TypeError`。
+
+### Pipeline
+
+| 方法 | 说明 |
+|------|------|
+| `use(fn)` | 注册中间件 |
+| `dispatch(ctx)` | 启动中间件链，返回 `Promise<void>` |
+
+### PipelineContext
+
+| 属性 | 类型 | 说明 |
+|------|------|------|
+| `args` | `TInput` | 原始入参，中间件可改写 |
+| `state` | `Record<string, unknown>` | 中间件间共享状态 |
+
+## License
+
+MIT

package/SKILL.md

@@ -0,0 +1,71 @@
+---
+name: model
+description: "@hile/model: defineModel/loadModel 定义和消费模型；services 依赖注入；pipeline 中间件链；每次 loadModel 重新执行 main"
+---
+
+# @hile/model
+
+与仓库根 **`SKILL.md`** 一并遵守。
+
+## 核心概念
+
+- **模型（Model）**：封装一段业务逻辑，通过 `defineModel` 定义，`loadModel` 执行
+- **Services 注入**：通过 `services` 声明依赖，`main` 首参为加载后的实例元组
+- **Pipeline**：Koa 风格中间件链，在 `main` 前后执行横切逻辑
+- **非单例**：每次 `loadModel` 都重新执行 `main`，不同于 `@hile/core` 的容器单例
+
+## 导出
+
+| 名称 | 说明 |
+|------|------|
+| `defineModel` | 定义模型，接收 `(main)` 简写或 `ModelProps` 对象 |
+| `loadModel` | `loadModel(model, input)` 执行模型 |
+| `isModel` | 判断值是否为 `defineModel` 返回值 |
+| `ModelDefinition` | 模型类型 |
+| `ModelProps` | `defineModel` 入参类型 |
+| `ModelPipeline` | `readonly PipelineMiddleware[]` |
+| `Pipeline` | 中间件链类 |
+| `PipelineContext` | 中间件上下文 |
+| `PipelineMiddleware` | 中间件类型 `(ctx, next) => Promise<void>` |
+| `InferServiceResult` | 工具类型 |
+| `InferredServices` | 工具类型 |
+
+## 用法规则
+
+### defineModel
+
+```typescript
+// 简写：无 services、无 pipelines
+defineModel(async (input: TInput) => R)
+
+// 完整形式
+defineModel({
+  services?: [ServiceA, ServiceB],       // 可选
+  pipelines?: [MiddlewareA, MiddlewareB], // 可选，顺序执行
+  async main(
+    services?: [InstanceA, InstanceB],    // 有 services 时首参
+    input: TInput,                        // 入参
+  ): R | Promise<R>,
+})
+```
+
+### 强制规则
+
+1. **模型文件**：一个文件一个 `defineModel`，`export default`
+2. **`loadModel` 首参**：必须是 `defineModel` 返回值，否则抛 `TypeError`
+3. **Pipeline 原则**：
+   - 最后一个中间件不应调用 `next()`，否则抛错
+   - 中间件短路（不调 `next()`）会使 `main` 不执行
+   - 中间件可通过 `ctx.args` 改写入参
+   - 中间件间通过 `ctx.state` 传递数据
+4. **Services**：同一 key 的 service 由 `@hile/core` 容器保证单例；model 本身不缓存结果
+
+## 反模式
+
+- 请求内调用 `defineModel`（应在模块顶层定义一次）
+- 手动构造 `ModelDefinition` 对象（必须通过 `defineModel`）
+- 在 `main` 中做副作用不返回结果（model 应是有输入有输出的纯业务函数）
+
+## 测试
+
+**`src/model.test.ts`**：`defineModel` 各种形式（完整、简写、services、pipelines）。**`src/pipeline.test.ts`**：中间件顺序、短路、next 多次调用、并发、无中间件等。

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { Pipeline, PipelineContext, type PipelineMiddleware, } from "./pipeline.js";
+export { defineModel, loadModel, isModel, type InferServiceResult, type InferredServices, type ModelDefinition, type ModelFlag, type ModelPipeline, type ModelProps, } from "./model.js";

package/dist/index.js

@@ -0,0 +1,2 @@
+export { Pipeline, PipelineContext, } from "./pipeline.js";
+export { defineModel, loadModel, isModel, } from "./model.js";

package/dist/model.d.ts

@@ -0,0 +1,40 @@
+import { type ServiceRegisterProps } from '@hile/core';
+import { type PipelineMiddleware } from './pipeline.js';
+declare const modelFlag: unique symbol;
+/** `defineModel` 返回值上的标记类型 */
+export type ModelFlag = typeof modelFlag;
+/** model 可用的 pipeline 中间件列表（默认可跨 model 复用） */
+export type ModelPipeline = readonly PipelineMiddleware[];
+/** 从 `ServiceRegisterProps` 推断 `loadService` 后的实例类型 */
+export type InferServiceResult<S> = S extends ServiceRegisterProps<infer R> ? R : never;
+/** `services` 元组 → `main` 首参元组（顺序与 `services` 一致） */
+export type InferredServices<S extends readonly ServiceRegisterProps<any>[]> = {
+    readonly [K in keyof S]: InferServiceResult<S[K]>;
+};
+/** `defineModel` 入参；`services` 可选；业务入参为对象 `input` */
+export type ModelProps<S extends readonly ServiceRegisterProps<any>[] | undefined = undefined, TInput extends object = Record<string, unknown>, R = unknown> = {
+    services?: S;
+    pipelines?: ModelPipeline;
+    main: S extends readonly ServiceRegisterProps<any>[] ? (services: InferredServices<S>, input: TInput) => R | Promise<R> : (input: TInput) => R | Promise<R>;
+};
+/**
+ * `defineModel` 的统一返回值；仅应由 {@link defineModel} 构造。
+ *
+ * 对外统一通过 `handler(input)` 调用。
+ */
+export type ModelDefinition<TInput extends object = Record<string, unknown>, R = unknown> = {
+    readonly flag: ModelFlag;
+    readonly handler: (input: TInput) => Promise<R>;
+};
+/**
+ * 使用给定参数执行 `model.handler(input)`，并以 Promise 返回其结果
+ *（`handler` 内同步抛错也会变为 reject）。
+ */
+export declare function loadModel<TInput extends object, R>(model: ModelDefinition<TInput, R>, input: TInput): Promise<R>;
+/** 判断值是否为 {@link defineModel} 的返回值 */
+export declare function isModel(value: unknown): value is ModelDefinition;
+/** 无 services / pipelines 时可直接传入 main：`defineModel(async (input) => ...)` */
+export declare function defineModel<TInput extends object, R>(main: (input: TInput) => R | Promise<R>): ModelDefinition<TInput, R>;
+/** `defineModel({ services?: [A, B], pipelines?: [PA, PB], async main(services?, input) { ... } })` */
+export declare function defineModel<const S extends readonly ServiceRegisterProps<any>[] | undefined = undefined, TInput extends object = Record<string, unknown>, R = unknown>(options: ModelProps<S, TInput, R>): ModelDefinition<TInput, R>;
+export {};

package/dist/model.js

@@ -0,0 +1,50 @@
+import { loadService } from '@hile/core';
+import { Pipeline, PipelineContext, } from './pipeline.js';
+const modelFlag = Symbol.for('@hile/model');
+/**
+ * 使用给定参数执行 `model.handler(input)`，并以 Promise 返回其结果
+ *（`handler` 内同步抛错也会变为 reject）。
+ */
+export function loadModel(model, input) {
+    if (!isModel(model)) {
+        return Promise.reject(new TypeError('loadModel: first argument must be a return value of defineModel'));
+    }
+    return model.handler(input);
+}
+/** 判断值是否为 {@link defineModel} 的返回值 */
+export function isModel(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        value.flag === modelFlag &&
+        typeof value.handler === 'function');
+}
+export function defineModel(optionsOrMain) {
+    if (typeof optionsOrMain === 'function') {
+        return defineModel({ main: optionsOrMain });
+    }
+    const { services, pipelines, main } = optionsOrMain;
+    const invokeMain = async (input) => {
+        if (services !== undefined) {
+            const loaded = await Promise.all(services.map((service) => loadService(service)));
+            return Promise.resolve(main(loaded, input));
+        }
+        return Promise.resolve(main(input));
+    };
+    const handler = async (input) => {
+        if (pipelines !== undefined && pipelines.length > 0) {
+            const ctx = new PipelineContext(input);
+            const chain = new Pipeline();
+            let result;
+            for (const middleware of pipelines) {
+                chain.use(middleware);
+            }
+            chain.use(async (ctx) => {
+                result = await invokeMain(ctx.args);
+            });
+            await chain.dispatch(ctx);
+            return result;
+        }
+        return invokeMain(input);
+    };
+    return { flag: modelFlag, handler };
+}

package/dist/model.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/model.test.js

@@ -0,0 +1,108 @@
+import { describe, it, expect } from 'vitest';
+import { defineService } from '@hile/core';
+import { defineModel, isModel, loadModel } from './model.js';
+const A = defineService('test.a', async () => ({ a: 1 }));
+const B = defineService('test.b', async () => ({ b: 2 }));
+const PA = async (_ctx, next) => next();
+const PB = async (_ctx, next) => next();
+describe('defineModel', () => {
+    it('handler 可调用（services + pipelines + main）', async () => {
+        const m = defineModel({
+            services: [A, B],
+            pipelines: [PA, PB],
+            async main([a, b], input) {
+                return { a, b, id: input.id };
+            },
+        });
+        expect(typeof m.handler).toBe('function');
+        expect(m.flag).toBe(Symbol.for('@hile/model'));
+        expect(isModel(m)).toBe(true);
+        const result = await m.handler({ id: 42 });
+        expect(result).toEqual({ a: { a: 1 }, b: { b: 2 }, id: 42 });
+    });
+    it('无 services：pipelines + main', async () => {
+        const m = defineModel({
+            pipelines: [PA, PB],
+            async main(input) {
+                return input.id;
+            },
+        });
+        await expect(m.handler({ id: 7 })).resolves.toBe(7);
+    });
+    it('无 services、无 pipelines：仅 main', async () => {
+        const m = defineModel({
+            async main(input) {
+                return input.id;
+            },
+        });
+        await expect(m.handler({ id: 3 })).resolves.toBe(3);
+    });
+    it('无 services、无 pipelines：函数简写', async () => {
+        const m = defineModel(async (input) => input.id);
+        expect(isModel(m)).toBe(true);
+        await expect(m.handler({ id: 3 })).resolves.toBe(3);
+        await expect(loadModel(m, { id: 9 })).resolves.toBe(9);
+    });
+    it('services + main（无 pipelines）', async () => {
+        const m = defineModel({
+            services: [A],
+            async main([a], input) {
+                return { a, id: input.id };
+            },
+        });
+        await expect(m.handler({ id: 1 })).resolves.toEqual({ a: { a: 1 }, id: 1 });
+    });
+    it('返回值符合 ModelDefinition', () => {
+        const m = defineModel({
+            services: [A],
+            async main([a], input) {
+                return { a, id: input.id };
+            },
+        });
+        expect(isModel(m)).toBe(true);
+    });
+    it('isModel 拒绝非 defineModel 对象', () => {
+        expect(isModel(null)).toBe(false);
+        expect(isModel({ handler: async () => ({}) })).toBe(false);
+    });
+    it('pipeline 可改写 ctx.args', async () => {
+        const m = defineModel({
+            pipelines: [
+                async (ctx, next) => {
+                    Object.assign(ctx.args, { id: 99 });
+                    await next();
+                },
+            ],
+            async main(input) {
+                return input.id;
+            },
+        });
+        await expect(m.handler({ id: 1 })).resolves.toBe(99);
+    });
+    it('loadModel 调用 handler', async () => {
+        const m = defineModel({
+            services: [A],
+            async main([a], input) {
+                return { a, id: input.id, name: input.name };
+            },
+        });
+        await expect(loadModel(m, { id: 1, name: 'test' })).resolves.toEqual({
+            a: { a: 1 },
+            id: 1,
+            name: 'test',
+        });
+    });
+    it('loadModel 非 model 应 reject', async () => {
+        await expect(loadModel({ handler: async () => 1 }, { id: 1 })).rejects.toThrow('loadModel: first argument must be a return value of defineModel');
+    });
+    it('services: [] 时 main 收到空元组', async () => {
+        const m = defineModel({
+            services: [],
+            async main(services, input) {
+                expect(services).toEqual([]);
+                return input.id;
+            },
+        });
+        await expect(m.handler({ id: 5 })).resolves.toBe(5);
+    });
+});

package/dist/pipeline.d.ts

@@ -0,0 +1,12 @@
+export type PipelineMiddleware<TInput extends object = Record<string, unknown>> = (ctx: PipelineContext<TInput>, next: () => Promise<void>) => Promise<void>;
+export declare class PipelineContext<TInput extends object = Record<string, unknown>> {
+    state: Record<string, unknown>;
+    readonly args: TInput;
+    constructor(args: TInput);
+}
+export declare class Pipeline<TInput extends object = Record<string, unknown>> {
+    private fns;
+    use(fn: PipelineMiddleware<TInput>): void;
+    /** 与 Koa compose 一致：只驱动中间件链，不返回值；结果由中间件写入 `ctx.state` */
+    dispatch(ctx: PipelineContext<TInput>): Promise<void>;
+}

package/dist/pipeline.js

@@ -0,0 +1,31 @@
+export class PipelineContext {
+    state = {};
+    args;
+    constructor(args) {
+        this.args = args;
+    }
+}
+export class Pipeline {
+    fns = [];
+    use(fn) {
+        this.fns.push(fn);
+    }
+    /** 与 Koa compose 一致：只驱动中间件链，不返回值；结果由中间件写入 `ctx.state` */
+    dispatch(ctx) {
+        const fns = this.fns;
+        if (fns.length === 0) {
+            return Promise.reject(new Error("pipeline: no middleware registered"));
+        }
+        let index = -1;
+        const run = async (i) => {
+            if (i <= index)
+                throw new Error("next() called multiple times");
+            index = i;
+            const fn = fns[i];
+            if (!fn)
+                throw new Error("pipeline: last middleware called next(), it should be terminal");
+            await fn(ctx, () => run(i + 1));
+        };
+        return run(0);
+    }
+}

package/dist/pipeline.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/pipeline.test.js

@@ -0,0 +1,171 @@
+import { describe, it, expect } from "vitest";
+import { Pipeline, PipelineContext } from "./pipeline.js";
+describe("Pipeline", () => {
+    it("executes middleware in order", async () => {
+        const order = [];
+        const p = new Pipeline();
+        p.use(async (ctx, next) => {
+            order.push(1);
+            await next();
+            order.push(4);
+        });
+        p.use(async (ctx, next) => {
+            order.push(2);
+            await next();
+            order.push(3);
+        });
+        p.use(async (ctx) => {
+            order.push(5);
+            ctx.state.result = ctx.args.value;
+        });
+        const ctx = new PipelineContext({ value: 42 });
+        await p.dispatch(ctx);
+        expect(ctx.state.result).toBe(42);
+        expect(order).toEqual([1, 2, 5, 3, 4]);
+    });
+    it("passes context through the chain", async () => {
+        const p = new Pipeline();
+        p.use(async (ctx, next) => {
+            ctx.args.msg += " > middleware1";
+            await next();
+        });
+        p.use(async (ctx, next) => {
+            ctx.args.msg += " > middleware2";
+            await next();
+        });
+        p.use(async (ctx) => {
+            ctx.state.result = ctx.args.msg;
+        });
+        const ctx = new PipelineContext({ msg: "start" });
+        await p.dispatch(ctx);
+        expect(ctx.state.result).toBe("start > middleware1 > middleware2");
+    });
+    it("allows middleware to short-circuit", async () => {
+        const p = new Pipeline();
+        let executed = false;
+        p.use(async (ctx, _next) => {
+            ctx.state.result = "short-circuited";
+        });
+        p.use(async (ctx, _next) => {
+            executed = true;
+            ctx.state.result = "should not reach";
+        });
+        const ctx = new PipelineContext({ value: "input" });
+        await p.dispatch(ctx);
+        expect(ctx.state.result).toBe("short-circuited");
+        expect(executed).toBe(false);
+    });
+    it("rejects if next() is called multiple times", async () => {
+        const p = new Pipeline();
+        p.use(async (ctx, next) => {
+            await next();
+            await expect(next()).rejects.toThrow("next() called multiple times");
+            ctx.state.result = "done";
+        });
+        p.use(async (ctx) => {
+            ctx.state.result = ctx.args.value;
+        });
+        const ctx = new PipelineContext({ value: "ok" });
+        await p.dispatch(ctx);
+        expect(ctx.state.result).toBe("done");
+    });
+    it("rejects if the last middleware calls next()", async () => {
+        const p = new Pipeline();
+        p.use(async (_ctx, next) => next());
+        const ctx = new PipelineContext({ value: "x" });
+        await expect(p.dispatch(ctx)).rejects.toThrow("last middleware called next");
+    });
+    it("rejects if no middleware registered", async () => {
+        const p = new Pipeline();
+        const ctx = new PipelineContext({ value: "x" });
+        await expect(p.dispatch(ctx)).rejects.toThrow("no middleware registered");
+    });
+    it("rejects on sync throw in middleware", async () => {
+        const p = new Pipeline();
+        p.use(() => {
+            throw new Error("sync error");
+        });
+        const ctx = new PipelineContext({ value: "x" });
+        await expect(p.dispatch(ctx)).rejects.toThrow("sync error");
+    });
+    it("rejects on async throw in middleware", async () => {
+        const p = new Pipeline();
+        p.use(async () => {
+            throw new Error("async error");
+        });
+        const ctx = new PipelineContext({ value: "x" });
+        await expect(p.dispatch(ctx)).rejects.toThrow("async error");
+    });
+    it("supports concurrent dispatch calls", async () => {
+        const p = new Pipeline();
+        p.use(async (_ctx, next) => next());
+        p.use(async (ctx) => {
+            ctx.state.result = ctx.args.id;
+        });
+        const ctx1 = new PipelineContext({ id: 1 });
+        const ctx2 = new PipelineContext({ id: 2 });
+        const ctx3 = new PipelineContext({ id: 3 });
+        await Promise.all([p.dispatch(ctx1), p.dispatch(ctx2), p.dispatch(ctx3)]);
+        expect(ctx1.state.result).toBe(1);
+        expect(ctx2.state.result).toBe(2);
+        expect(ctx3.state.result).toBe(3);
+    });
+    it("allows middleware to modify result from downstream", async () => {
+        const p = new Pipeline();
+        p.use(async (ctx, next) => {
+            await next();
+            ctx.state.result = ctx.state.result * 2;
+        });
+        p.use(async (ctx) => {
+            ctx.state.result = ctx.args.n + 1;
+        });
+        const ctx = new PipelineContext({ n: 3 });
+        await p.dispatch(ctx);
+        expect(ctx.state.result).toBe(8);
+    });
+    it("works with single terminal middleware", async () => {
+        const p = new Pipeline();
+        p.use(async (ctx) => {
+            ctx.state.result = ctx.args.value;
+        });
+        const ctx = new PipelineContext({ value: "ok" });
+        await p.dispatch(ctx);
+        expect(ctx.state.result).toBe("ok");
+    });
+    it("composes multiple middleware correctly", async () => {
+        const log = [];
+        const p = new Pipeline();
+        p.use(async (_ctx, next) => {
+            log.push("A:enter");
+            await next();
+            log.push("A:exit");
+        });
+        p.use(async (_ctx, next) => {
+            log.push("B:enter");
+            await next();
+            log.push("B:exit");
+        });
+        p.use(async (ctx) => {
+            log.push("terminal");
+            ctx.state.result = ctx.args.n * 10;
+        });
+        const ctx = new PipelineContext({ n: 3 });
+        await p.dispatch(ctx);
+        expect(ctx.state.result).toBe(30);
+        expect(log).toEqual(["A:enter", "B:enter", "terminal", "B:exit", "A:exit"]);
+    });
+    it("downstream layers can read ctx.state.result after next()", async () => {
+        const p = new Pipeline();
+        p.use(async (ctx, next) => {
+            await next();
+            expect(ctx.state.result).toBe(2);
+            ctx.state.result = ctx.state.result + 10;
+        });
+        p.use(async (ctx) => {
+            ctx.state.result = ctx.args.id + 1;
+        });
+        const ctx = new PipelineContext({ id: 1 });
+        await p.dispatch(ctx);
+        expect(ctx.state.result).toBe(12);
+    });
+});

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "@hile/model",
+  "version": "2.0.0",
+  "type": "module",
+  "main": "./dist/index.js",
+  "scripts": {
+    "build": "tsc -b && fix-esm-import-path --preserve-import-type ./dist",
+    "dev": "tsc -b --watch",
+    "test": "vitest run"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "SKILL.md"
+  ],
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "fix-esm-import-path": "^1.10.3",
+    "vitest": "^4.0.18"
+  },
+  "dependencies": {
+    "@hile/core": "^1.1.2"
+  },
+  "gitHead": "ec6272f3e39d3afaefd12d9d70ba2b103c5f122a"
+}