@fluojs/mongoose 1.1.0 → 2.0.0

package/README.ko.md

@@ -1,6 +1,7 @@
 # @fluojs/mongoose
 
 <p><a href="./README.md"><kbd>English</kbd></a> <strong><kbd>한국어</kbd></strong></p>
+<!-- fluo-mongoose-contract: application-owned-connection, ambient-session-merge, preserves-operation-options, strict-fail-open, explicit-target -->
 
 세션 인지형 트랜잭션 처리와 라이프사이클 친화적인 외부 연결 관리를 제공하는 fluo용 Mongoose 통합 패키지입니다.
 
@@ -12,6 +13,8 @@
 - [라이프사이클과 종료](#라이프사이클과-종료)
 - [공통 패턴](#공통-패턴)
   - [서비스 트랜잭션 경계 (@Transaction)](#서비스-트랜잭션-경계-transaction)
+  - [기존 문서 저장](#기존-문서-저장)
+  - [요청 트랜잭션 인터셉터 호환성](#요청-트랜잭션-인터셉터-호환성)
   - [수동 트랜잭션과 currentSession()](#수동-트랜잭션과-currentsession)
 - [공개 API](#공개-api)
 - [관련 패키지](#관련-패키지)
@@ -28,8 +31,11 @@ pnpm add mongoose
 
 - Mongoose를 나머지 애플리케이션과 같은 DI 및 라이프사이클 모델에 연결하고 싶을 때.
 - 모든 서비스에서 MongoDB 세션과 트랜잭션을 임시 배관 코드 없이 하나의 wrapper로 다루고 싶을 때.
+- 요청 단위 트랜잭션에 명시적 `requestTransaction(...)` 경계가 필요할 때.
 - 애플리케이션이 이미 concrete Mongoose connection을 생성·구성하고 있고, fluo가 그 ownership을 대체하지 않고 관측하기를 원할 때.
 
+Root `@fluojs/mongoose` wrapper는 ambient transaction context에 Node.js `node:async_hooks`를 사용하며 패키지 자체의 지원 계약으로 Node.js `>=24.0.0 <27`을 요구합니다. Node 20 및 Node 22 host를 Node.js `>=24.0.0 <27`로 올리세요. Node 24 미만과 Node 27 이상은 지원하지 않습니다. 비 Node 런타임에서는 runtime-specific transaction-context adapter가 문서화되기 전까지 root wrapper를 import하지 말고 raw Mongoose-compatible handle을 애플리케이션 소유 provider 뒤에 등록하세요.
+
 ## 빠른 시작
 
 루트 모듈에 Mongoose 연결 인스턴스를 전달하여 `MongooseModule`을 등록합니다.
@@ -61,10 +67,12 @@ class AppModule {}
 종료 절차는 트랜잭션 정리 순서를 보존하고, 종료가 시작된 뒤에는 새로운 수동 또는 요청 단위 트랜잭션 경계를 거부합니다.
 
 1. 열린 요청 단위 트랜잭션은 `Application shutdown interrupted an open request transaction.`으로 abort됩니다.
-2. 활성 ambient session은 transaction callback과 session cleanup이 settle될 때까지 추적됩니다.
-3. 해당 Mongoose 세션은 `abortTransaction()`과 `endSession()` 정리를 끝냅니다.
+2. 활성 ambient session, 원본 request callback, fail-open 직접 실행 transaction callback은 작업이 settle될 때까지 추적됩니다.
+3. 해당 Mongoose 세션은 시작된 callback이 settle된 뒤에만 `abortTransaction()`과 `endSession()` 정리를 끝냅니다.
 4. 설정한 `dispose(connection)` 훅은 활성 요청 트랜잭션과 ambient session scope가 모두 settled된 뒤에만 실행됩니다.
 
+Request cancellation 또는 shutdown이 callback 시작 후 boundary를 abort하면, boundary는 abort 결과를 보존하되 원본 callback이 settle될 때까지 기다린 다음 rollback, session 종료, connection dispose를 진행합니다. 따라서 ALS-backed 작업이 이미 정리된 session이나 connection을 사용하며 계속 실행되지 않습니다.
+
 `MongooseConnection.createPlatformStatusSnapshot()`과 export된 low-level `createMongoosePlatformStatusSnapshot(...)` helper는 serving 중에는 `ready`, 요청 트랜잭션을 drain하는 shutdown 중에는 `shutting-down`, dispose hook 완료 후에는 `stopped`를 보고합니다. status details에는 `sessionStrategy`, `transactionContext: 'als'`, 활성 요청/세션 수, 리소스 소유권, strict/session 지원 진단이 포함됩니다. 수동 `transaction()` 호출과 서비스 `@Transaction()` 메서드는 같은 ambient session을 `conn.model(...)`에 노출합니다. 지원되는 facade 메서드(`create`, `find`, `findOne`, `aggregate`, `bulkWrite`)는 해당 세션을 자동으로 첨부합니다. 자동 세션 주입은 `MongooseConnection.model(...)` wrapper 메서드에만 scope되며, `conn.current()`가 반환하는 raw `connection.model(...)` cache/compile 경로를 교체하거나 변형하지 않습니다. 지원되지 않는 model 메서드, `doc.save()`, 외부 유틸리티에 명시적 세션 배관이 필요할 때는 `conn.currentSession()`을 사용하세요. 래핑된 Mongoose connection이 `connection.transaction(...)`을 제공하면 fluo는 Mongoose 자체 ambient-session scope를 보존하면서 동일한 세션을 `currentSession()`으로 노출하도록 해당 API에 트랜잭션 경계를 위임합니다. 요청 단위 트랜잭션은 세션을 획득하는 동안과 위임된 `connection.transaction(...)` 작업을 시작하는 동안 request `AbortSignal`을 관찰하므로, request cancellation은 사용자 callback이 실행되기 전의 startup phase를 중단할 수 있습니다.
 
 기존 수동 `transaction(...)` boundary 안에서 열린 중첩 `requestTransaction(...)` 호출은 ambient session을 재사용하고 `details.activeRequestTransactions`에 계속 표시되며, 종료 중에 abort되어 바깥 수동 transaction이 `dispose(connection)` 실행 전에 rollback할 수 있습니다.
@@ -76,37 +84,100 @@ class AppModule {}
 `@Transaction()` 데코레이터는 서비스 레이어에서 트랜잭션 경계를 정의하는 권장 방법입니다. 이 데코레이터가 적용된 메서드 내부에서 발생하는 모든 리포지토리 호출은 동일한 MongoDB 세션을 공유합니다.
 
 ```ts
-import { Transaction } from '@fluojs/mongoose';
-import { UserRepository } from './user.repository';
+import { Inject } from '@fluojs/core';
+import { MongooseConnection, Transaction, type MongooseModelFacade } from '@fluojs/mongoose';
+
+type UserDocumentSaveOptions = {
+  readonly validateBeforeSave?: boolean;
+  readonly session?: object | null;
+};
+type UserDocument = {
+  readonly _id: string;
+  readonly name: string;
+  save(options?: UserDocumentSaveOptions): Promise<UserDocument>;
+};
+type UserCreateModel = MongooseModelFacade<Promise<readonly [UserDocument]>>;
+type ProfileCreateModel = MongooseModelFacade<Promise<readonly { readonly userId: string }[]>>;
+
+@Inject(MongooseConnection)
+export class UserRepository {
+  constructor(private readonly conn: MongooseConnection) {}
+
+  async create(data: CreateUserDto) {
+    // @Transaction() 내부에서 conn.model()은 세션 인지형 facade를 반환합니다.
+    // create, find, findOne, aggregate, bulkWrite 등의 작업은
+    // 자동으로 활성 트랜잭션에 참여합니다.
+    return this.conn.model<UserCreateModel>('User').create([data]);
+  }
 
+  async initProfile(userId: string) {
+    return this.conn.model<ProfileCreateModel>('Profile').create([{ userId }]);
+  }
+}
+
+@Inject(UserRepository)
 export class UserService {
   constructor(private readonly repo: UserRepository) {}
 
   @Transaction()
   async onboardUser(dto: CreateUserDto) {
-    const user = await this.repo.create(dto);
+    const [user] = await this.repo.create(dto);
     await this.repo.initProfile(user._id);
     return user;
   }
 }
+```
 
-export class UserRepository {
-  constructor(private readonly conn: MongooseConnection) {}
+`@Transaction()` 메서드 호출은 재진입(reentrant)이 가능합니다. 데코레이터가 적용된 메서드가 다른 데코레이터 적용 메서드를 호출하더라도 하나의 동일한 MongoDB 세션 안에서 실행됩니다. 참고로 v1에서 `doc.save()`는 자동으로 세션을 주입하지 않으므로, 자동 트랜잭션 참여가 필요하다면 지원되는 facade 작업(`model.create()`, `model.find()`, `model.findOne()`, `model.aggregate()`, `model.bulkWrite()`)을 사용하세요.
 
-  async create(data: any) {
-    // @Transaction() 내부에서 conn.model()은 세션 인지형 facade를 반환합니다.
-    // create, find, findOne, aggregate, bulkWrite 등의 작업은
-    // 자동으로 활성 트랜잭션에 참여합니다.
-    return this.conn.model('User').create(data);
+`@Transaction()`은 `this.conn`, transaction-capable한 decorated instance 자체, 또는 하나뿐인 중첩 `this.*.conn` collaborator를 해석합니다. 임의의 connection field를 선택하지는 않습니다. 서비스가 여러 connection을 소유하거나 다른 field에 connection을 저장하는 경우에는 경계를 명시적으로 선택하세요.
+
+```ts
+@Inject(MongooseConnection)
+export class AnalyticsService {
+  constructor(private readonly analyticsConnection: MongooseConnection) {}
+
+  @Transaction((self: AnalyticsService) => self.analyticsConnection)
+  async rebuildReports() {
+    // 추론된 connection 대신 analyticsConnection을 사용합니다.
   }
+}
+```
+
+### 기존 문서 저장
+
+<!-- fluo-mongoose-save-document-contract: opt-in, active-session, save-compatible-document -->
+
+기존 Mongoose 문서를 활성 `@Transaction()`, `transaction()`, `requestTransaction()` 경계 안에서 저장해야 하면 opt-in `MongooseConnection.saveDocument(...)` helper를 사용하세요.
 
-  async initProfile(userId: any) {
-    return this.conn.model('Profile').create({ userId });
+```ts
+@Transaction()
+async rename(document: UserDocument) {
+  return this.conn.saveDocument(document, { validateBeforeSave: false });
+}
+```
+
+helper는 native Mongoose save option을 전달하고 ambient session을 붙인 뒤 동일한 document instance를 반환합니다. 활성 트랜잭션 밖에서는 fail-closed하며, 실수로 현재 트랜잭션을 벗어나지 않도록 `{ session: null }` 또는 다른 명시적 session을 거부합니다. document, prototype, model cache를 patch하지 않으므로 `doc.save()` 직접 호출은 계속 native Mongoose 동작이며 자동 session을 받지 않습니다.
+
+### 요청 트랜잭션 인터셉터 호환성
+
+`MongooseTransactionInterceptor`는 기존 request-wide `@UseInterceptors(...)` boundary를 위한 deprecated 1.x 호환성 export로 복원되었습니다. `MongooseModule.forRoot(...)`와 `forRootAsync(...)`가 이 interceptor를 provider 및 export로 제공하며, `MongooseConnection.requestTransaction(...)`에 위임하고 request `AbortSignal`을 전달합니다.
+
+```ts
+import { Controller, Post, UseInterceptors } from '@fluojs/http';
+import { MongooseTransactionInterceptor } from '@fluojs/mongoose';
+
+@Controller('/orders')
+export class OrdersController {
+  @Post('/')
+  @UseInterceptors(MongooseTransactionInterceptor)
+  createOrder() {
+    return this.orders.create();
   }
 }
 ```
 
-`@Transaction()` 메서드 호출은 재진입(reentrant)이 가능합니다. 데코레이터가 적용된 메서드가 다른 데코레이터 적용 메서드를 호출하더라도 하나의 동일한 MongoDB 세션 안에서 실행됩니다. 참고로 v1에서 `doc.save()`는 자동으로 세션을 주입하지 않으므로, 자동 트랜잭션 참여가 필요하다면 지원되는 facade 작업(`model.create()`, `model.find()`, `model.findOne()`, `model.aggregate()`, `model.bulkWrite()`)을 사용하세요.
+새 비즈니스 작업에는 서비스 계층 `@Transaction()`을 우선 사용하세요. 기존 request-wide boundary를 migration하는 동안에만 이 interceptor를 유지하고, request orchestration에서 경계를 명시해야 한다면 `requestTransaction(...)` 직접 호출로 교체하세요.
 
 ### 수동 트랜잭션과 currentSession()
 
@@ -137,17 +208,19 @@ await this.conn.transaction(async () => {
 });
 ```
 
-래핑된 연결이 `connection.transaction(...)`을 구현하고 있다면 fluo는 이를 엄격한 트랜잭션 경계로 취급합니다. 그렇지 않고 `startSession()`이 없는 경우 트랜잭션은 기본값(`strictTransactions: false`)에서 callback 직접 실행으로 fail-open합니다. 이 모드는 local fake나 staged migration에는 유용하지만 rollback 원자성은 제공하지 않습니다. MongoDB transaction 보장이 필요한 production 흐름에서는 `strictTransactions: true`를 설정하세요. 그러면 transaction 지원 누락이 readiness `not-ready`와 helper 예외로 드러납니다.
+래핑된 연결이 `connection.transaction(...)`을 구현하고 있다면 fluo는 이를 엄격한 트랜잭션 경계로 취급합니다. 그렇지 않고 `startSession()`이 없는 경우 트랜잭션은 기본값(`strictTransactions: false`)에서 callback 직접 실행으로 fail-open합니다. 이 모드는 local fake나 staged migration에는 유용하지만 rollback 원자성은 제공하지 않습니다. 열린 fail-open 수동 `transaction(...)` callback도 종료 중에 drain되므로 `dispose(connection)`은 해당 callback이 settle된 뒤 실행됩니다. MongoDB transaction 보장이 필요한 production 흐름에서는 `strictTransactions: true`를 설정하세요. 그러면 transaction 지원 누락이 readiness `not-ready`와 helper 예외로 드러납니다.
 
-지원되는 facade 메서드에서 fluo는 기존 Mongoose 작업 옵션을 보존하고 올바른 options 인자에 ambient `{ session }`만 병합합니다. 활성 트랜잭션 내부에서 명시적으로 `{ session: null }`을 전달하거나 다른 세션 객체를 사용하면, 의도치 않은 트랜잭션 탈출을 방지하기 위해 세션 충돌 에러를 발생시킵니다.
+지원되는 facade 메서드에서 fluo는 기존 Mongoose 작업 옵션을 보존하고 올바른 options 인자에 ambient `{ session }`만 병합합니다. `create(...)`는 Mongoose의 array overload인 `create([docs], options?)`를 통해서만 session을 주입합니다. Positional `create(docA, docB)` 인자는 마지막 문서에 `timestamps` 같은 option-like field가 있어도 그대로 전달되며 자동 session 주입을 받지 않습니다. 트랜잭션 참여가 필요하면 array overload를 사용하세요. 활성 트랜잭션 내부에서 명시적으로 `{ session: null }`을 전달하거나 다른 세션 객체를 사용하면, `findOne(filter, projection, options)`의 세 번째 options 인자를 포함해 의도치 않은 트랜잭션 탈출을 방지하는 세션 충돌 에러를 발생시킵니다. Repository code에서 typed operation result가 필요하면 result-specialized `MongooseModelFacade`를 `model<TModel>(...)` 타입 인자로 전달하세요.
 
 ## 공개 API
 
+- `MongooseConnection.saveDocument(document, options?)` — native save option과 document identity를 보존하면서 현재 트랜잭션 session으로 기존 문서를 명시적으로 저장합니다.
 - `MongooseModule.forRoot(options)` / `MongooseModule.forRootAsync(options)`
 - `MongooseConnection`
 - `MongooseConnection.createPlatformStatusSnapshot()` — platform observability surface를 위해 health/readiness, resource ownership, 활성 request/session drain 수, strict transaction 지원 진단을 보고합니다.
-- `MongooseConnection.model(name, ...args)` — 트랜잭션 밖에서는 raw model을 반환하고, 활성 트랜잭션 안에서는 underlying Mongoose connection을 변형하지 않으면서 `create`, `find`, `findOne`, `aggregate`, `bulkWrite`에 세션을 주입하는 facade를 반환합니다.
+- `MongooseConnection.model<TModel>(name, ...args)` — 트랜잭션 밖에서는 callable하고 result-specializable한 `MongooseModelFacade`를 반환하고, 활성 트랜잭션 안에서는 underlying Mongoose connection을 변형하지 않으면서 `create`, `find`, `findOne`, `aggregate`, `bulkWrite`에 세션을 주입하는 버전을 반환합니다.
 - `Transaction`
+- `MongooseTransactionInterceptor` — deprecated request-wide 호환성 interceptor입니다. 새 코드에서는 서비스 `@Transaction()` 또는 명시적 `requestTransaction(...)`을 우선 사용하세요.
 - `MONGOOSE_CONNECTION`, `MONGOOSE_DISPOSE`, `MONGOOSE_OPTIONS`
 - `createMongooseProviders(options)` — 호환성/수동 composition helper입니다. 애플리케이션-facing 등록에서는 module export와 provider visibility가 문서화된 namespace facade와 맞도록 `MongooseModule.forRoot(...)` 또는 `MongooseModule.forRootAsync(...)`를 우선 사용하세요.
 - `createMongoosePlatformStatusSnapshot(...)`
@@ -160,6 +233,7 @@ await this.conn.transaction(async () => {
 - `MongooseAsyncModuleOptions<TConnection>`
 - `MongooseConnectionLike`
 - `MongooseSessionLike`
+- `MongooseModelFacade`
 - `MongooseHandleProvider`
 - `MongoosePlatformStatusSnapshotInput`
 

package/README.md

@@ -1,6 +1,7 @@
 # @fluojs/mongoose
 
 <p><strong><kbd>English</kbd></strong> <a href="./README.ko.md"><kbd>한국어</kbd></a></p>
+<!-- fluo-mongoose-contract: application-owned-connection, ambient-session-merge, preserves-operation-options, strict-fail-open, explicit-target -->
 
 Mongoose integration for fluo with session-aware transaction handling and lifecycle-friendly connection management.
 
@@ -12,6 +13,8 @@ Mongoose integration for fluo with session-aware transaction handling and lifecy
 - [Lifecycle and Shutdown](#lifecycle-and-shutdown)
 - [Common Patterns](#common-patterns)
   - [Service Transaction Boundary (@Transaction)](#service-transaction-boundary-transaction)
+  - [Saving an Existing Document](#saving-an-existing-document)
+  - [Request Transaction Interceptor Compatibility](#request-transaction-interceptor-compatibility)
   - [Manual Transactions and currentSession()](#manual-transactions-and-currentsession)
 - [Public API](#public-api)
 - [Related Packages](#related-packages)
@@ -31,6 +34,8 @@ pnpm add mongoose
 - when request-scoped transactions need explicit `requestTransaction(...)` boundaries
 - when an application already creates and configures its concrete Mongoose connection and wants fluo to observe, not replace, that ownership
 
+The root `@fluojs/mongoose` wrapper uses Node.js `node:async_hooks` for ambient transaction context and requires Node.js `>=24.0.0 <27` as its package-owned support contract. Upgrade Node 20 and Node 22 hosts to Node.js `>=24.0.0 <27`; Node versions below 24 and Node 27+ are unsupported. For non-Node runtimes, register raw Mongoose-compatible handles behind application-owned providers instead of importing the root wrapper until a runtime-specific transaction-context adapter is documented.
+
 ## Quick Start
 
 ```ts
@@ -60,10 +65,12 @@ class AppModule {}
 Shutdown preserves transaction cleanup order and rejects new manual or request-scoped transaction boundaries once shutdown begins:
 
 1. Open request-scoped transactions are aborted with `Application shutdown interrupted an open request transaction.`
-2. Active ambient sessions are tracked until their transaction callback and session cleanup settle.
-3. Their Mongoose sessions finish `abortTransaction()` and `endSession()` cleanup.
+2. Active ambient sessions, original request callbacks, and fail-open direct-execution transaction callbacks are tracked until their work settles.
+3. Their Mongoose sessions finish `abortTransaction()` and `endSession()` cleanup only after started callbacks settle.
 4. The configured `dispose(connection)` hook runs only after active request transactions and ambient session scopes have settled.
 
+When request cancellation or shutdown aborts a boundary after its callback has started, the boundary preserves the abort result but waits for the original callback to settle before rolling back, ending the session, or disposing the connection. This prevents ALS-backed work from continuing against an already-cleaned-up session or connection.
+
 `MongooseConnection.createPlatformStatusSnapshot()` and the exported low-level `createMongoosePlatformStatusSnapshot(...)` helper report `ready` while serving traffic, `shutting-down` while request transactions are draining, and `stopped` after the dispose hook completes. The status details include `sessionStrategy`, `transactionContext: 'als'`, active request/session counts, resource ownership, and strict/session support diagnostics. Manual `transaction()` calls and service `@Transaction()` methods expose the same ambient session to `conn.model(...)`; supported facade methods (`create`, `find`, `findOne`, `aggregate`, and `bulkWrite`) automatically attach that session. Automatic session injection is scoped to the `MongooseConnection.model(...)` wrapper method and does not replace or mutate the raw `connection.model(...)` cache/compile path returned by `conn.current()`. Use `conn.currentSession()` for unsupported model methods, `doc.save()`, or external utilities that need explicit session plumbing. If the wrapped Mongoose connection exposes `connection.transaction(...)`, fluo delegates the transaction boundary to that API so Mongoose's own ambient-session scope is preserved while still exposing the same session through `currentSession()`. Request-scoped transactions observe the request `AbortSignal` while acquiring sessions and while starting delegated `connection.transaction(...)` work, so request cancellation can interrupt those startup phases before user callbacks run.
 Nested `requestTransaction(...)` calls opened inside an existing manual `transaction(...)` boundary reuse the ambient session, stay visible in `details.activeRequestTransactions`, and are aborted during shutdown so the outer manual transaction can roll back before `dispose(connection)` runs.
 
@@ -74,37 +81,100 @@ Nested `requestTransaction(...)` calls opened inside an existing manual `transac
 The `@Transaction()` decorator is the recommended way to define transaction boundaries in your service layer. It ensures that all repository calls made within the decorated method share the same MongoDB session.
 
 ```ts
-import { Transaction } from '@fluojs/mongoose';
-import { UserRepository } from './user.repository';
+import { Inject } from '@fluojs/core';
+import { MongooseConnection, Transaction, type MongooseModelFacade } from '@fluojs/mongoose';
+
+type UserDocumentSaveOptions = {
+  readonly validateBeforeSave?: boolean;
+  readonly session?: object | null;
+};
+type UserDocument = {
+  readonly _id: string;
+  readonly name: string;
+  save(options?: UserDocumentSaveOptions): Promise<UserDocument>;
+};
+type UserCreateModel = MongooseModelFacade<Promise<readonly [UserDocument]>>;
+type ProfileCreateModel = MongooseModelFacade<Promise<readonly { readonly userId: string }[]>>;
+
+@Inject(MongooseConnection)
+export class UserRepository {
+  constructor(private readonly conn: MongooseConnection) {}
+
+  async create(data: CreateUserDto) {
+    // model() returns a session-aware facade inside @Transaction().
+    // Operations like create, find, findOne, aggregate, and bulkWrite
+    // automatically participate in the ambient transaction.
+    return this.conn.model<UserCreateModel>('User').create([data]);
+  }
 
+  async initProfile(userId: string) {
+    return this.conn.model<ProfileCreateModel>('Profile').create([{ userId }]);
+  }
+}
+
+@Inject(UserRepository)
 export class UserService {
   constructor(private readonly repo: UserRepository) {}
 
   @Transaction()
   async onboardUser(dto: CreateUserDto) {
-    const user = await this.repo.create(dto);
+    const [user] = await this.repo.create(dto);
     await this.repo.initProfile(user._id);
     return user;
   }
 }
+```
 
-export class UserRepository {
-  constructor(private readonly conn: MongooseConnection) {}
+Calls to `@Transaction()` methods are reentrant. If a decorated method calls another decorated method, they share the same underlying MongoDB session. Note that `doc.save()` is not automatically session-aware in v1; use the supported facade operations (`model.create()`, `model.find()`, `model.findOne()`, `model.aggregate()`, or `model.bulkWrite()`) for automatic transaction participation.
 
-  async create(data: any) {
-    // model() returns a session-aware facade inside @Transaction().
-    // Operations like create, find, findOne, aggregate, and bulkWrite
-    // automatically participate in the ambient transaction.
-    return this.conn.model('User').create(data);
+`@Transaction()` resolves `this.conn`, the decorated instance when it is transaction-capable, or one unique nested `this.*.conn` collaborator. It does not select arbitrary connection fields. When a service owns multiple connections or stores its connection elsewhere, select the boundary explicitly:
+
+```ts
+@Inject(MongooseConnection)
+export class AnalyticsService {
+  constructor(private readonly analyticsConnection: MongooseConnection) {}
+
+  @Transaction((self: AnalyticsService) => self.analyticsConnection)
+  async rebuildReports() {
+    // Uses analyticsConnection rather than an inferred connection.
   }
+}
+```
+
+### Saving an Existing Document
+
+<!-- fluo-mongoose-save-document-contract: opt-in, active-session, save-compatible-document -->
+
+Use the opt-in `MongooseConnection.saveDocument(...)` helper when an existing Mongoose document must save inside an active `@Transaction()`, `transaction()`, or `requestTransaction()` boundary:
 
-  async initProfile(userId: any) {
-    return this.conn.model('Profile').create({ userId });
+```ts
+@Transaction()
+async rename(document: UserDocument) {
+  return this.conn.saveDocument(document, { validateBeforeSave: false });
+}
+```
+
+The helper forwards native Mongoose save options, attaches the ambient session, and returns the same document instance. It fails closed outside an active transaction and rejects `{ session: null }` or a different explicit session so a save cannot leave the current transaction accidentally. It never patches documents, prototypes, or model caches: calling `doc.save()` directly remains native Mongoose behavior and does not receive an automatic session.
+
+### Request Transaction Interceptor Compatibility
+
+`MongooseTransactionInterceptor` is restored as a deprecated 1.x compatibility export for existing request-wide `@UseInterceptors(...)` boundaries. `MongooseModule.forRoot(...)` and `forRootAsync(...)` provide and export it. It delegates to `MongooseConnection.requestTransaction(...)` and forwards the request `AbortSignal`.
+
+```ts
+import { Controller, Post, UseInterceptors } from '@fluojs/http';
+import { MongooseTransactionInterceptor } from '@fluojs/mongoose';
+
+@Controller('/orders')
+export class OrdersController {
+  @Post('/')
+  @UseInterceptors(MongooseTransactionInterceptor)
+  createOrder() {
+    return this.orders.create();
   }
 }
 ```
 
-Calls to `@Transaction()` methods are reentrant. If a decorated method calls another decorated method, they share the same underlying MongoDB session. Note that `doc.save()` is not automatically session-aware in v1; use the supported facade operations (`model.create()`, `model.find()`, `model.findOne()`, `model.aggregate()`, or `model.bulkWrite()`) for automatic transaction participation.
+Prefer service-layer `@Transaction()` for new business operations. Keep this interceptor only while migrating existing request-wide boundaries, or replace it with an explicit `requestTransaction(...)` call when request orchestration must make the boundary visible.
 
 ### Manual Transactions and currentSession()
 
@@ -135,17 +205,19 @@ await this.conn.transaction(async () => {
 });
 ```
 
-If the wrapped connection implements `connection.transaction(...)`, fluo treats that as the strict transaction boundary. Otherwise, when the connection does not implement `startSession()`, transactions use fail-open direct callback execution by default (`strictTransactions: false`), which is useful for local fakes and staged migrations but provides no rollback atomicity. Set `strictTransactions: true` for production flows that require MongoDB transaction guarantees; missing transaction support then makes readiness `not-ready` and causes transaction helpers to throw.
+If the wrapped connection implements `connection.transaction(...)`, fluo treats that as the strict transaction boundary. Otherwise, when the connection does not implement `startSession()`, transactions use fail-open direct callback execution by default (`strictTransactions: false`), which is useful for local fakes and staged migrations but provides no rollback atomicity. Open fail-open manual `transaction(...)` callbacks still drain during shutdown before `dispose(connection)` runs. Set `strictTransactions: true` for production flows that require MongoDB transaction guarantees; missing transaction support then makes readiness `not-ready` and causes transaction helpers to throw.
 
-For supported facade methods, fluo preserves existing Mongoose operation options and only merges the ambient `{ session }` into the correct options argument. If a model call passes an explicit `{ session: null }` or a different session object inside an ambient transaction, fluo throws a session conflict error to prevent accidental transaction escapes.
+For supported facade methods, fluo preserves existing Mongoose operation options and only merges the ambient `{ session }` into the correct options argument. `create(...)` injects the session only through Mongoose's array overload, `create([docs], options?)`. Positional `create(docA, docB)` arguments are forwarded unchanged—even when the last document contains option-like fields such as `timestamps`—and therefore do not receive automatic session injection. Use the array overload for transaction participation. If a model call passes an explicit `{ session: null }` or a different session object inside an ambient transaction, including the third options argument of `findOne(filter, projection, options)`, fluo throws a session conflict error to prevent accidental transaction escapes. Pass a result-specialized `MongooseModelFacade` as the `model<TModel>(...)` type argument when repository code needs typed operation results.
 
 ## Public API
 
+- `MongooseConnection.saveDocument(document, options?)` — explicitly saves an existing document with the current transaction session while preserving native save options and document identity.
 - `MongooseModule.forRoot(options)` / `MongooseModule.forRootAsync(options)`
 - `MongooseConnection`
 - `MongooseConnection.createPlatformStatusSnapshot()` — reports health/readiness, resource ownership, active request/session drain counts, and strict transaction support diagnostics for platform observability surfaces.
-- `MongooseConnection.model(name, ...args)` — returns the raw model outside transactions or a session-aware facade for `create`, `find`, `findOne`, `aggregate`, and `bulkWrite` inside an active transaction without mutating the underlying Mongoose connection.
+- `MongooseConnection.model<TModel>(name, ...args)` — returns the callable, result-specializable `MongooseModelFacade` outside transactions or a session-aware version for `create`, `find`, `findOne`, `aggregate`, and `bulkWrite` inside an active transaction without mutating the underlying Mongoose connection.
 - `Transaction`
+- `MongooseTransactionInterceptor` — deprecated request-wide compatibility interceptor; prefer service `@Transaction()` or explicit `requestTransaction(...)` in new code.
 - `MONGOOSE_CONNECTION`, `MONGOOSE_DISPOSE`, `MONGOOSE_OPTIONS`
 - `createMongooseProviders(options)` — compatibility/manual composition helper; prefer `MongooseModule.forRoot(...)` or `MongooseModule.forRootAsync(...)` for application-facing registration so module exports and provider visibility stay aligned.
 - `createMongoosePlatformStatusSnapshot(...)`
@@ -158,6 +230,7 @@ For supported facade methods, fluo preserves existing Mongoose operation options
 - `MongooseAsyncModuleOptions<TConnection>`
 - `MongooseConnectionLike`
 - `MongooseSessionLike`
+- `MongooseModelFacade`
 - `MongooseHandleProvider`
 - `MongoosePlatformStatusSnapshotInput`
 

package/dist/connection.d.ts

@@ -1,9 +1,8 @@
 import type { OnApplicationShutdown } from '@fluojs/runtime';
-import type { MongooseConnectionLike, MongooseHandleProvider, MongooseSessionLike } from './types.js';
+import type { MongooseConnectionLike, MongooseHandleProvider, MongooseModelFacade, MongooseSessionLike } from './types.js';
 type MongooseRuntimeOptions = {
     strictTransactions: boolean;
 };
-type MongooseModelLike = Record<PropertyKey, unknown>;
 /**
  * Session-aware Mongoose wrapper that integrates request scoping and shutdown handling with the Fluo runtime.
  *
@@ -16,6 +15,7 @@ export declare class MongooseConnection<TConnection extends MongooseConnectionLi
     private readonly sessions;
     private readonly activeRequestTransactions;
     private readonly activeSessions;
+    private readonly activeTransactionCallbacks;
     private lifecycleState;
     constructor(connection: TConnection, dispose?: ((connection: TConnection) => Promise<void> | void) | undefined, connectionOptions?: MongooseRuntimeOptions);
     /**
@@ -40,14 +40,31 @@ export declare class MongooseConnection<TConnection extends MongooseConnectionLi
      * @returns The ambient session inside a transaction boundary, or `undefined` outside one.
      */
     currentSession(): MongooseSessionLike | undefined;
+    /**
+     * Saves a Mongoose document with the active transaction session.
+     *
+     * This opt-in helper preserves the document instance and forwards caller-provided save options.
+     * It does not patch document instances, prototypes, or model caches.
+     *
+     * @typeParam TSaveOptions Options accepted by the document's native `save()` method.
+     * @typeParam TDocument Mongoose document-like value being saved.
+     * @param document Existing Mongoose document to save.
+     * @param options Native Mongoose save options to preserve while attaching the ambient session.
+     * @returns The same document instance after its native save operation completes.
+     * @throws When called outside an active transaction or with a conflicting explicit session.
+     */
+    saveDocument<TSaveOptions extends object, TDocument extends {
+        save(options?: TSaveOptions): Promise<TDocument>;
+    }>(document: TDocument, options?: TSaveOptions): Promise<TDocument>;
     /**
      * Returns a model from the root connection, injecting the ambient transaction session into conservative operations.
      *
+     * @typeParam TModel Consumer-defined facade result contract for the wrapped model.
      * @param name Model name passed to the underlying Mongoose connection.
      * @param args Additional model resolver arguments forwarded unchanged.
      * @returns The real model outside transactions, or a model facade inside an active transaction boundary.
      */
-    model(name: string, ...args: unknown[]): MongooseModelLike;
+    model<TModel extends MongooseModelFacade = MongooseModelFacade>(name: string, ...args: unknown[]): TModel;
     /** Aborts active request transactions, waits for settlement, then runs the optional dispose hook. */
     onApplicationShutdown(): Promise<void>;
     /** Produces the shared persistence status snapshot for platform diagnostics surfaces. */
@@ -82,9 +99,11 @@ export declare class MongooseConnection<TConnection extends MongooseConnectionLi
     private assertTransactionsAvailable;
     private assertRequestTransactionsAvailable;
     private runManualSessionTransaction;
+    private runDirectTransaction;
     private resolveSessionForRequest;
     private runConnectionTransaction;
     private trackActiveSession;
+    private trackActiveTransactionCallback;
     private trackActiveRequestTransaction;
     private untrackActiveRequestTransaction;
     private resolveSession;

package/dist/connection.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"connection.d.ts","sourceRoot":"","sources":["../src/connection.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,iBAAiB,CAAC;AAS7D,OAAO,KAAK,EACV,sBAAsB,EACtB,sBAAsB,EACtB,mBAAmB,EACpB,MAAM,YAAY,CAAC;AAuBpB,KAAK,sBAAsB,GAAG;IAC5B,kBAAkB,EAAE,OAAO,CAAC;CAC7B,CAAC;AAEF,KAAK,iBAAiB,GAAG,MAAM,CAAC,WAAW,EAAE,OAAO,CAAC,CAAC;AAyJtD;;;;GAIG;AACH,qBACa,kBAAkB,CAAC,WAAW,SAAS,sBAAsB,GAAG,sBAAsB,CACjG,YAAW,sBAAsB,CAAC,WAAW,CAAC,EAAE,qBAAqB;IAQnE,OAAO,CAAC,QAAQ,CAAC,UAAU;IAC3B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC;IACzB,OAAO,CAAC,QAAQ,CAAC,iBAAiB;IARpC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAgD;IACzE,OAAO,CAAC,QAAQ,CAAC,yBAAyB,CAAuC;IACjF,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAiC;IAChE,OAAO,CAAC,cAAc,CAAkD;gBAGrD,UAAU,EAAE,WAAW,EACvB,OAAO,CAAC,GAAE,CAAC,UAAU,EAAE,WAAW,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,aAAA,EAC3D,iBAAiB,GAAE,sBAAsD;IAG5F;;;;;;;;;OASG;IACH,OAAO,IAAI,WAAW;IAItB;;;;;;;;;OASG;IACH,cAAc,IAAI,mBAAmB,GAAG,SAAS;IAIjD;;;;;;OAMG;IACH,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,iBAAiB;IAa1D,qGAAqG;IAC/F,qBAAqB,IAAI,OAAO,CAAC,IAAI,CAAC;IAmB5C,yFAAyF;IACzF,4BAA4B;IAY5B;;;;;;;;;;;;OAYG;IACG,WAAW,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;IAoBtD;;;;;;;;;;;OAWG;IACG,kBAAkB,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,CAAC,CAAC;IA+CnF,OAAO,CAAC,2BAA2B;IAMnC,OAAO,CAAC,kCAAkC;YAM5B,2BAA2B;YAc3B,wBAAwB;YA4BxB,wBAAwB;IActC,OAAO,CAAC,kBAAkB;IAkB1B,OAAO,CAAC,6BAA6B;IAIrC,OAAO,CAAC,+BAA+B;YAIzB,cAAc;CAW7B"}
+{"version":3,"file":"connection.d.ts","sourceRoot":"","sources":["../src/connection.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,iBAAiB,CAAC;AAS7D,OAAO,KAAK,EACV,sBAAsB,EACtB,sBAAsB,EACtB,mBAAmB,EACnB,mBAAmB,EACpB,MAAM,YAAY,CAAC;AAqCpB,KAAK,sBAAsB,GAAG;IAC5B,kBAAkB,EAAE,OAAO,CAAC;CAC7B,CAAC;AA0IF;;;;GAIG;AACH,qBACa,kBAAkB,CAAC,WAAW,SAAS,sBAAsB,GAAG,sBAAsB,CACjG,YAAW,sBAAsB,CAAC,WAAW,CAAC,EAAE,qBAAqB;IASnE,OAAO,CAAC,QAAQ,CAAC,UAAU;IAC3B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC;IACzB,OAAO,CAAC,QAAQ,CAAC,iBAAiB;IATpC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAgD;IACzE,OAAO,CAAC,QAAQ,CAAC,yBAAyB,CAAuC;IACjF,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAiC;IAChE,OAAO,CAAC,QAAQ,CAAC,0BAA0B,CAAwC;IACnF,OAAO,CAAC,cAAc,CAAkD;gBAGrD,UAAU,EAAE,WAAW,EACvB,OAAO,CAAC,GAAE,CAAC,UAAU,EAAE,WAAW,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,aAAA,EAC3D,iBAAiB,GAAE,sBAAsD;IAG5F;;;;;;;;;OASG;IACH,OAAO,IAAI,WAAW;IAItB;;;;;;;;;OASG;IACH,cAAc,IAAI,mBAAmB,GAAG,SAAS;IAIjD;;;;;;;;;;;;OAYG;IACG,YAAY,CAChB,YAAY,SAAS,MAAM,EAC3B,SAAS,SAAS;QAAE,IAAI,CAAC,OAAO,CAAC,EAAE,YAAY,GAAG,OAAO,CAAC,SAAS,CAAC,CAAA;KAAE,EACtE,QAAQ,EAAE,SAAS,EAAE,OAAO,CAAC,EAAE,YAAY,GAAG,OAAO,CAAC,SAAS,CAAC;IASlE;;;;;;;OAOG;IACH,KAAK,CAAC,MAAM,SAAS,mBAAmB,GAAG,mBAAmB,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,MAAM;IAczG,qGAAqG;IAC/F,qBAAqB,IAAI,OAAO,CAAC,IAAI,CAAC;IAoB5C,yFAAyF;IACzF,4BAA4B;IAY5B;;;;;;;;;;;;OAYG;IACG,WAAW,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;IA6BtD;;;;;;;;;;;OAWG;IACG,kBAAkB,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,CAAC,CAAC;IAwDnF,OAAO,CAAC,2BAA2B;IAMnC,OAAO,CAAC,kCAAkC;YAM5B,2BAA2B;YAmB3B,oBAAoB;YAQpB,wBAAwB;YA4BxB,wBAAwB;IActC,OAAO,CAAC,kBAAkB;IA2B1B,OAAO,CAAC,8BAA8B;IAkBtC,OAAO,CAAC,6BAA6B;IAIrC,OAAO,CAAC,+BAA+B;YAIzB,cAAc;CAW7B"}

package/dist/connection.js

@@ -13,52 +13,31 @@ const TRANSACTIONS_NOT_SUPPORTED_ERROR = 'Transaction not supported: Mongoose co
 const TRANSACTION_UNAVAILABLE_ERROR = 'Mongoose transactions are unavailable during application shutdown.';
 const MODEL_OPERATIONS_WITH_OPTIONS = new Set(['aggregate', 'bulkWrite', 'create', 'find', 'findOne']);
 const MODEL_OPERATIONS_WITH_PROJECTION = new Set(['find', 'findOne']);
-const MONGOOSE_CREATE_OPTION_KEYS = new Set(['aggregateErrors', 'checkKeys', 'j', 'ordered', 'populate', 'safe', 'session', 'timestamps', 'validateBeforeSave', 'validateModifiedOnly', 'w', 'writeConcern', 'wtimeout']);
-function hasExplicitSessionOption(value) {
-  return value !== null && typeof value === 'object' && 'session' in value;
-}
 function isObjectLike(value) {
   return typeof value === 'object' && value !== null || typeof value === 'function';
 }
-function isMongooseCreateOptionsCandidate(value) {
-  if (!isObjectLike(value)) {
-    return false;
-  }
-  for (const key of MONGOOSE_CREATE_OPTION_KEYS) {
-    if (key in value) {
-      return true;
-    }
-  }
-  return false;
-}
-function isEmptyCreateOptionsCandidate(value) {
-  return value !== null && typeof value === 'object' && !Array.isArray(value) && Object.keys(value).length === 0;
-}
 function resolveCreateOptionsIndex(operationArgs) {
-  if (operationArgs.length >= 2 && isMongooseCreateOptionsCandidate(operationArgs[operationArgs.length - 1])) {
-    return operationArgs.length - 1;
-  }
-  if (operationArgs.length === 2 && Array.isArray(operationArgs[0])) {
+  if (Array.isArray(operationArgs[0])) {
     return 1;
   }
-  if (operationArgs.length === 2 && isEmptyCreateOptionsCandidate(operationArgs[1])) {
-    return 1;
-  }
-  return operationArgs.length;
+  return undefined;
+}
+function resolveAggregateOptionsIndex() {
+  return 1;
 }
 function resolveOptionsIndex(operation, operationArgs) {
   if (operation === 'create') {
     return resolveCreateOptionsIndex(operationArgs);
   }
+  if (operation === 'aggregate') {
+    return resolveAggregateOptionsIndex();
+  }
   if (!MODEL_OPERATIONS_WITH_PROJECTION.has(operation)) {
     return operationArgs.length > 1 ? 1 : operationArgs.length;
   }
   if (operationArgs.length >= 3) {
     return 2;
   }
-  if (operationArgs.length === 2 && hasExplicitSessionOption(operationArgs[1])) {
-    return 1;
-  }
   if (operationArgs.length <= 1) {
     return 2;
   }
@@ -87,12 +66,29 @@ function createAmbientSessionModelFacade(model, ambient) {
       return (...args) => {
         const operationArgs = [...args];
         const optionsIndex = resolveOptionsIndex(prop, operationArgs);
+        if (optionsIndex === undefined) {
+          return value.apply(target, operationArgs);
+        }
         operationArgs[optionsIndex] = resolveSessionOptions(operationArgs[optionsIndex], ambient);
         return value.apply(target, operationArgs);
       };
     }
   });
 }
+async function raceWithAbortAndDrainCallback(fn, signal, shouldDrainAfterAbort = () => true) {
+  let callback;
+  try {
+    return await raceWithAbort(() => {
+      callback = Promise.resolve().then(fn);
+      return callback;
+    }, signal);
+  } catch (error) {
+    if (signal.aborted && callback && shouldDrainAfterAbort()) {
+      await callback.then(() => undefined, () => undefined);
+    }
+    throw error;
+  }
+}
 function resolveModelFactory(connection) {
   if (!isObjectLike(connection)) {
     return undefined;
@@ -129,6 +125,7 @@ class MongooseConnection {
   sessions = new AsyncLocalStorage();
   activeRequestTransactions = new Set();
   activeSessions = new Set();
+  activeTransactionCallbacks = new Set();
   lifecycleState = 'ready';
   constructor(connection, dispose, connectionOptions = {
     strictTransactions: false
@@ -163,16 +160,39 @@ class MongooseConnection {
    * @returns The ambient session inside a transaction boundary, or `undefined` outside one.
    */
   currentSession() {
-    return this.sessions.getStore();
+    return this.sessions.getStore()?.session;
+  }
+
+  /**
+   * Saves a Mongoose document with the active transaction session.
+   *
+   * This opt-in helper preserves the document instance and forwards caller-provided save options.
+   * It does not patch document instances, prototypes, or model caches.
+   *
+   * @typeParam TSaveOptions Options accepted by the document's native `save()` method.
+   * @typeParam TDocument Mongoose document-like value being saved.
+   * @param document Existing Mongoose document to save.
+   * @param options Native Mongoose save options to preserve while attaching the ambient session.
+   * @returns The same document instance after its native save operation completes.
+   * @throws When called outside an active transaction or with a conflicting explicit session.
+   */
+  async saveDocument(document, options) {
+    const session = this.currentSession();
+    if (!session) {
+      throw new Error('Mongoose document saves require an active transaction session.');
+    }
+    return document.save(resolveSessionOptions(options, session));
   }
 
   /**
    * Returns a model from the root connection, injecting the ambient transaction session into conservative operations.
    *
+   * @typeParam TModel Consumer-defined facade result contract for the wrapped model.
    * @param name Model name passed to the underlying Mongoose connection.
    * @param args Additional model resolver arguments forwarded unchanged.
    * @returns The real model outside transactions, or a model facade inside an active transaction boundary.
    */
+
   model(name, ...args) {
     const modelFactory = resolveModelFactory(this.connection);
     if (typeof modelFactory !== 'function') {
@@ -189,7 +209,7 @@ class MongooseConnection {
     for (const transaction of this.activeRequestTransactions) {
       transaction.abort(new Error('Application shutdown interrupted an open request transaction.'));
     }
-    await Promise.allSettled([...Array.from(this.activeRequestTransactions, transaction => transaction.settled), ...Array.from(this.activeSessions, session => session.settled)]);
+    await Promise.allSettled([...Array.from(this.activeRequestTransactions, transaction => transaction.settled), ...Array.from(this.activeSessions, session => session.settled), ...Array.from(this.activeTransactionCallbacks, callback => callback.settled)]);
     if (this.dispose) {
       await this.dispose(this.connection);
     }
@@ -231,11 +251,18 @@ class MongooseConnection {
     if (typeof this.connection.transaction === 'function') {
       return this.runConnectionTransaction(fn);
     }
-    const session = await this.resolveSession();
+    const activeCallback = this.trackActiveTransactionCallback();
+    let session;
+    try {
+      session = await this.resolveSession();
+    } catch (error) {
+      activeCallback.settle();
+      throw error;
+    }
     if (!session) {
-      return fn();
+      return this.runDirectTransaction(fn, activeCallback);
     }
-    return this.runManualSessionTransaction(session, fn);
+    return this.runManualSessionTransaction(session, fn, activeCallback);
   }
 
   /**
@@ -251,16 +278,16 @@ class MongooseConnection {
    * @returns The callback result after the request transaction finishes or the direct-execution fallback completes.
    */
   async requestTransaction(fn, signal) {
-    const currentSession = this.sessions.getStore();
-    if (currentSession) {
+    const currentScope = this.sessions.getStore();
+    if (currentScope) {
       this.assertRequestTransactionsAvailable();
       const abortContext = createRequestAbortContext(signal);
       const active = this.trackActiveRequestTransaction(abortContext.controller);
       try {
-        return await raceWithAbort(fn, abortContext.signal);
+        return await raceWithAbortAndDrainCallback(fn, abortContext.signal);
       } finally {
         abortContext.cleanup();
-        this.untrackActiveRequestTransaction(active);
+        currentScope.activeSession.retainRequestTransaction(active);
       }
     }
     this.assertRequestTransactionsAvailable();
@@ -269,15 +296,20 @@ class MongooseConnection {
     let untrackActiveInFinally = true;
     try {
       if (typeof this.connection.transaction === 'function') {
-        return await raceWithAbort(() => this.runConnectionTransaction(() => raceWithAbort(fn, abortContext.signal)), abortContext.signal);
+        let delegatedCallbackStarted = false;
+        const delegatedTransaction = this.runConnectionTransaction(() => {
+          delegatedCallbackStarted = true;
+          return raceWithAbortAndDrainCallback(fn, abortContext.signal);
+        });
+        return await raceWithAbortAndDrainCallback(() => delegatedTransaction, abortContext.signal, () => delegatedCallbackStarted);
       }
       const resolvedSession = await this.resolveSessionForRequest(abortContext.signal, active, () => {
         untrackActiveInFinally = false;
       });
       if (!resolvedSession) {
-        return await raceWithAbort(fn, abortContext.signal);
+        return await raceWithAbortAndDrainCallback(fn, abortContext.signal);
       }
-      return await this.runManualSessionTransaction(resolvedSession, () => raceWithAbort(fn, abortContext.signal));
+      return await this.runManualSessionTransaction(resolvedSession, () => raceWithAbortAndDrainCallback(fn, abortContext.signal));
     } finally {
       abortContext.cleanup();
       if (untrackActiveInFinally) {
@@ -295,18 +327,29 @@ class MongooseConnection {
       throw new Error(TRANSACTION_UNAVAILABLE_ERROR);
     }
   }
-  async runManualSessionTransaction(session, fn) {
+  async runManualSessionTransaction(session, fn, activeCallback) {
     const activeSession = this.trackActiveSession();
     try {
-      return await this.sessions.run(session, () => executeSessionTransaction(session, fn));
+      return await this.sessions.run({
+        activeSession,
+        session
+      }, () => executeSessionTransaction(session, fn));
     } finally {
       try {
         await session.endSession();
       } finally {
         activeSession.settle();
+        activeCallback?.settle();
       }
     }
   }
+  async runDirectTransaction(fn, activeCallback) {
+    try {
+      return await fn();
+    } finally {
+      activeCallback.settle();
+    }
+  }
   async resolveSessionForRequest(signal, active, deferActiveSettlement) {
     const sessionPromise = this.resolveSession();
     try {
@@ -330,7 +373,10 @@ class MongooseConnection {
       if (typeof this.connection.transaction !== 'function') {
         throw new Error('Mongoose connection transaction resolver initialization failed.');
       }
-      return await this.connection.transaction(session => this.sessions.run(session, fn));
+      return await this.connection.transaction(session => this.sessions.run({
+        activeSession,
+        session
+      }, fn));
     } finally {
       activeSession.settle();
     }
@@ -342,14 +388,37 @@ class MongooseConnection {
         settle = resolve;
       })
     };
+    const retainedRequestTransactions = new Set();
     this.activeSessions.add(active);
     return {
+      retainRequestTransaction: handle => {
+        retainedRequestTransactions.add(handle);
+      },
       settle: () => {
+        for (const handle of retainedRequestTransactions) {
+          this.untrackActiveRequestTransaction(handle);
+        }
+        retainedRequestTransactions.clear();
         this.activeSessions.delete(active);
         settle();
       }
     };
   }
+  trackActiveTransactionCallback() {
+    let settle;
+    const active = {
+      settled: new Promise(resolve => {
+        settle = resolve;
+      })
+    };
+    this.activeTransactionCallbacks.add(active);
+    return {
+      settle: () => {
+        this.activeTransactionCallbacks.delete(active);
+        settle();
+      }
+    };
+  }
   trackActiveRequestTransaction(controller) {
     return trackActiveRequestTransaction(this.activeRequestTransactions, controller);
   }

package/dist/module.d.ts

@@ -30,7 +30,7 @@ export declare class MongooseModule {
      * Registers Mongoose providers from static options.
      *
      * @param options Mongoose module options with connection handle, optional dispose hook, and strict transaction mode.
-     * @returns A module definition that exports `MongooseConnection`.
+     * @returns A module definition that exports `MongooseConnection` and its compatibility request interceptor.
      */
     static forRoot<TConnection extends MongooseConnectionLike>(options: MongooseModuleOptions<TConnection>): ModuleType;
     /**

package/dist/module.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"module.d.ts","sourceRoot":"","sources":["../src/module.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AACvD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAC3C,OAAO,EAAgB,KAAK,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAIhE,OAAO,KAAK,EAAE,sBAAsB,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC;AAahF;;;;;;GAMG;AACH,MAAM,MAAM,0BAA0B,CAAC,WAAW,SAAS,sBAAsB,IAAI,kBAAkB,CACrG,IAAI,CAAC,qBAAqB,CAAC,WAAW,CAAC,EAAE,QAAQ,CAAC,CACnD,GAAG,IAAI,CAAC,qBAAqB,CAAC,WAAW,CAAC,EAAE,QAAQ,CAAC,CAAC;AA2EvD;;;;;;;;;;GAUG;AACH,wBAAgB,uBAAuB,CAAC,WAAW,SAAS,sBAAsB,EAChF,OAAO,EAAE,qBAAqB,CAAC,WAAW,CAAC,GAC1C,QAAQ,EAAE,CAOZ;AA0BD;;GAEG;AACH,qBAAa,cAAc;IACzB;;;;;OAKG;IACH,MAAM,CAAC,OAAO,CAAC,WAAW,SAAS,sBAAsB,EAAE,OAAO,EAAE,qBAAqB,CAAC,WAAW,CAAC,GAAG,UAAU;IAInH;;;;;OAKG;IACH,MAAM,CAAC,YAAY,CAAC,WAAW,SAAS,sBAAsB,EAC5D,OAAO,EAAE,0BAA0B,CAAC,WAAW,CAAC,GAC/C,UAAU;CAGd"}
+{"version":3,"file":"module.d.ts","sourceRoot":"","sources":["../src/module.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AACvD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAC3C,OAAO,EAAgB,KAAK,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAKhE,OAAO,KAAK,EAAE,sBAAsB,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC;AAahF;;;;;;GAMG;AACH,MAAM,MAAM,0BAA0B,CAAC,WAAW,SAAS,sBAAsB,IAAI,kBAAkB,CACrG,IAAI,CAAC,qBAAqB,CAAC,WAAW,CAAC,EAAE,QAAQ,CAAC,CACnD,GAAG,IAAI,CAAC,qBAAqB,CAAC,WAAW,CAAC,EAAE,QAAQ,CAAC,CAAC;AA4EvD;;;;;;;;;;GAUG;AACH,wBAAgB,uBAAuB,CAAC,WAAW,SAAS,sBAAsB,EAChF,OAAO,EAAE,qBAAqB,CAAC,WAAW,CAAC,GAC1C,QAAQ,EAAE,CAOZ;AA0BD;;GAEG;AACH,qBAAa,cAAc;IACzB;;;;;OAKG;IACH,MAAM,CAAC,OAAO,CAAC,WAAW,SAAS,sBAAsB,EAAE,OAAO,EAAE,qBAAqB,CAAC,WAAW,CAAC,GAAG,UAAU;IAInH;;;;;OAKG;IACH,MAAM,CAAC,YAAY,CAAC,WAAW,SAAS,sBAAsB,EAC5D,OAAO,EAAE,0BAA0B,CAAC,WAAW,CAAC,GAC/C,UAAU;CAGd"}

package/dist/module.js

@@ -1,6 +1,7 @@
 import { defineModule } from '@fluojs/runtime';
 import { MongooseConnection } from './connection.js';
 import { MONGOOSE_CONNECTION, MONGOOSE_DISPOSE, MONGOOSE_OPTIONS } from './tokens.js';
+import { MongooseTransactionInterceptor } from './transaction.js';
 
 /**
  * Async registration options accepted by `MongooseModule.forRootAsync(...)`.
@@ -11,7 +12,7 @@ import { MONGOOSE_CONNECTION, MONGOOSE_DISPOSE, MONGOOSE_OPTIONS } from './token
  */
 
 const MONGOOSE_NORMALIZED_OPTIONS = Symbol('fluo.mongoose.normalized-options');
-const MONGOOSE_MODULE_EXPORTS = [MongooseConnection];
+const MONGOOSE_MODULE_EXPORTS = [MongooseConnection, MongooseTransactionInterceptor];
 function isObjectLike(value) {
   return typeof value === 'object' && value !== null || typeof value === 'function';
 }
@@ -42,7 +43,7 @@ function createMongooseRuntimeProviders(normalizedOptionsProvider) {
     inject: [MONGOOSE_NORMALIZED_OPTIONS],
     provide: MONGOOSE_OPTIONS,
     useFactory: options => createRuntimeOptionsProviderValue(options.strictTransactions)
-  }, MongooseConnection];
+  }, MongooseConnection, MongooseTransactionInterceptor];
 }
 function createMongooseProvidersAsync(options) {
   const factory = options.useFactory;
@@ -104,7 +105,7 @@ export class MongooseModule {
    * Registers Mongoose providers from static options.
    *
    * @param options Mongoose module options with connection handle, optional dispose hook, and strict transaction mode.
-   * @returns A module definition that exports `MongooseConnection`.
+   * @returns A module definition that exports `MongooseConnection` and its compatibility request interceptor.
    */
   static forRoot(options) {
     return buildMongooseModule(options);

package/dist/transaction.d.ts

@@ -1,3 +1,6 @@
+import type { CallHandler, Interceptor, InterceptorContext } from '@fluojs/http';
+import { MongooseConnection } from './connection.js';
+import type { MongooseConnectionLike } from './types.js';
 type TransactionConnection = {
     transaction<T>(fn: () => Promise<T>): Promise<T>;
 };
@@ -16,5 +19,26 @@ type TransactionMethod<THost, TArgs extends unknown[], TResult> = (this: THost,
  * @returns A standard method decorator that executes the original method inside a Mongoose transaction.
  */
 export declare function Transaction<THost>(accessor?: (self: THost) => TransactionConnection): <TArgs extends unknown[], TResult>(value: TransactionMethod<THost, TArgs, TResult>, context: ClassMethodDecoratorContext<THost, TransactionMethod<THost, TArgs, TResult>>) => TransactionMethod<THost, TArgs, TResult>;
+/**
+ * Compatibility HTTP interceptor that opens a Mongoose request transaction around a routed handler.
+ *
+ * @remarks
+ * This deprecated 1.x bridge forwards the request `AbortSignal` to `MongooseConnection.requestTransaction(...)`.
+ * Prefer service-layer `@Transaction()` or an explicit request boundary for new code.
+ *
+ * @deprecated Prefer service-layer `@Transaction()` or explicit `MongooseConnection.requestTransaction(...)`.
+ */
+export declare class MongooseTransactionInterceptor implements Interceptor {
+    private readonly connection;
+    constructor(connection: MongooseConnection<MongooseConnectionLike>);
+    /**
+     * Runs the downstream handler inside the compatibility request transaction.
+     *
+     * @param context Interceptor context containing the request cancellation signal.
+     * @param next Downstream handler chain.
+     * @returns The downstream result after the request transaction settles.
+     */
+    intercept(context: InterceptorContext, next: CallHandler): Promise<unknown>;
+}
 export {};
 //# sourceMappingURL=transaction.d.ts.map

package/dist/transaction.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"transaction.d.ts","sourceRoot":"","sources":["../src/transaction.ts"],"names":[],"mappings":"AAAA,KAAK,qBAAqB,GAAG;IAC3B,WAAW,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;CAClD,CAAC;AAEF,KAAK,iBAAiB,CAAC,KAAK,EAAE,KAAK,SAAS,OAAO,EAAE,EAAE,OAAO,IAAI,CAChE,IAAI,EAAE,KAAK,EACX,GAAG,IAAI,EAAE,KAAK,KACX,OAAO,CAAC,OAAO,CAAC,CAAC;AA6DtB;;;;;;;;;;;;GAYG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAC/B,QAAQ,CAAC,EAAE,CAAC,IAAI,EAAE,KAAK,KAAK,qBAAqB,GAChD,CAAC,KAAK,SAAS,OAAO,EAAE,EAAE,OAAO,EAClC,KAAK,EAAE,iBAAiB,CAAC,KAAK,EAAE,KAAK,EAAE,OAAO,CAAC,EAC/C,OAAO,EAAE,2BAA2B,CAAC,KAAK,EAAE,iBAAiB,CAAC,KAAK,EAAE,KAAK,EAAE,OAAO,CAAC,CAAC,KAClF,iBAAiB,CAAC,KAAK,EAAE,KAAK,EAAE,OAAO,CAAC,CAW5C"}
+{"version":3,"file":"transaction.d.ts","sourceRoot":"","sources":["../src/transaction.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,WAAW,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAEjF,OAAO,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AACrD,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,YAAY,CAAC;AAEzD,KAAK,qBAAqB,GAAG;IAC3B,WAAW,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;CAClD,CAAC;AAEF,KAAK,iBAAiB,CAAC,KAAK,EAAE,KAAK,SAAS,OAAO,EAAE,EAAE,OAAO,IAAI,CAChE,IAAI,EAAE,KAAK,EACX,GAAG,IAAI,EAAE,KAAK,KACX,OAAO,CAAC,OAAO,CAAC,CAAC;AA6DtB;;;;;;;;;;;;GAYG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAC/B,QAAQ,CAAC,EAAE,CAAC,IAAI,EAAE,KAAK,KAAK,qBAAqB,GAChD,CAAC,KAAK,SAAS,OAAO,EAAE,EAAE,OAAO,EAClC,KAAK,EAAE,iBAAiB,CAAC,KAAK,EAAE,KAAK,EAAE,OAAO,CAAC,EAC/C,OAAO,EAAE,2BAA2B,CAAC,KAAK,EAAE,iBAAiB,CAAC,KAAK,EAAE,KAAK,EAAE,OAAO,CAAC,CAAC,KAClF,iBAAiB,CAAC,KAAK,EAAE,KAAK,EAAE,OAAO,CAAC,CAW5C;AAED;;;;;;;;GAQG;AACH,qBACa,8BAA+B,YAAW,WAAW;IACpD,OAAO,CAAC,QAAQ,CAAC,UAAU;gBAAV,UAAU,EAAE,kBAAkB,CAAC,sBAAsB,CAAC;IAEnF;;;;;;OAMG;IACG,SAAS,CAAC,OAAO,EAAE,kBAAkB,EAAE,IAAI,EAAE,WAAW,GAAG,OAAO,CAAC,OAAO,CAAC;CAGlF"}

package/dist/transaction.js

@@ -1,3 +1,11 @@
+let _initClass;
+function _applyDecs(e, t, n, r, o, i) { var a, c, u, s, f, l, p, d = Symbol.metadata || Symbol.for("Symbol.metadata"), m = Object.defineProperty, h = Object.create, y = [h(null), h(null)], v = t.length; function g(t, n, r) { return function (o, i) { n && (i = o, o = e); for (var a = 0; a < t.length; a++) i = t[a].apply(o, r ? [i] : []); return r ? i : o; }; } function b(e, t, n, r) { if ("function" != typeof e && (r || void 0 !== e)) throw new TypeError(t + " must " + (n || "be") + " a function" + (r ? "" : " or undefined")); return e; } function applyDec(e, t, n, r, o, i, u, s, f, l, p) { function d(e) { if (!p(e)) throw new TypeError("Attempted to access private element on non-instance"); } var h = [].concat(t[0]), v = t[3], w = !u, D = 1 === o, S = 3 === o, j = 4 === o, E = 2 === o; function I(t, n, r) { return function (o, i) { return n && (i = o, o = e), r && r(o), P[t].call(o, i); }; } if (!w) { var P = {}, k = [], F = S ? "get" : j || D ? "set" : "value"; if (f ? (l || D ? P = { get: _setFunctionName(function () { return v(this); }, r, "get"), set: function (e) { t[4](this, e); } } : P[F] = v, l || _setFunctionName(P[F], r, E ? "" : F)) : l || (P = Object.getOwnPropertyDescriptor(e, r)), !l && !f) { if ((c = y[+s][r]) && 7 !== (c ^ o)) throw Error("Decorating two elements with the same name (" + P[F].name + ") is not supported yet"); y[+s][r] = o < 3 ? 1 : o; } } for (var N = e, O = h.length - 1; O >= 0; O -= n ? 2 : 1) { var T = b(h[O], "A decorator", "be", !0), z = n ? h[O - 1] : void 0, A = {}, H = { kind: ["field", "accessor", "method", "getter", "setter", "class"][o], name: r, metadata: a, addInitializer: function (e, t) { if (e.v) throw new TypeError("attempted to call addInitializer after decoration was finished"); b(t, "An initializer", "be", !0), i.push(t); }.bind(null, A) }; if (w) c = T.call(z, N, H), A.v = 1, b(c, "class decorators", "return") && (N = c);else if (H.static = s, H.private = f, c = H.access = { has: f ? p.bind() : function (e) { return r in e; } }, j || (c.get = f ? E ? function (e) { return d(e), P.value; } : I("get", 0, d) : function (e) { return e[r]; }), E || S || (c.set = f ? I("set", 0, d) : function (e, t) { e[r] = t; }), N = T.call(z, D ? { get: P.get, set: P.set } : P[F], H), A.v = 1, D) { if ("object" == typeof N && N) (c = b(N.get, "accessor.get")) && (P.get = c), (c = b(N.set, "accessor.set")) && (P.set = c), (c = b(N.init, "accessor.init")) && k.unshift(c);else if (void 0 !== N) throw new TypeError("accessor decorators must return an object with get, set, or init properties or undefined"); } else b(N, (l ? "field" : "method") + " decorators", "return") && (l ? k.unshift(N) : P[F] = N); } return o < 2 && u.push(g(k, s, 1), g(i, s, 0)), l || w || (f ? D ? u.splice(-1, 0, I("get", s), I("set", s)) : u.push(E ? P[F] : b.call.bind(P[F])) : m(e, r, P)), N; } function w(e) { return m(e, d, { configurable: !0, enumerable: !0, value: a }); } return void 0 !== i && (a = i[d]), a = h(null == a ? null : a), f = [], l = function (e) { e && f.push(g(e)); }, p = function (t, r) { for (var i = 0; i < n.length; i++) { var a = n[i], c = a[1], l = 7 & c; if ((8 & c) == t && !l == r) { var p = a[2], d = !!a[3], m = 16 & c; applyDec(t ? e : e.prototype, a, m, d ? "#" + p : _toPropertyKey(p), l, l < 2 ? [] : t ? s = s || [] : u = u || [], f, !!t, d, r, t && d ? function (t) { return _checkInRHS(t) === e; } : o); } } }, p(8, 0), p(0, 0), p(8, 1), p(0, 1), l(u), l(s), c = f, v || w(e), { e: c, get c() { var n = []; return v && [w(e = applyDec(e, [t], r, e.name, 5, n)), g(n, 1)]; } }; }
+function _toPropertyKey(t) { var i = _toPrimitive(t, "string"); return "symbol" == typeof i ? i : i + ""; }
+function _toPrimitive(t, r) { if ("object" != typeof t || !t) return t; var e = t[Symbol.toPrimitive]; if (void 0 !== e) { var i = e.call(t, r || "default"); if ("object" != typeof i) return i; throw new TypeError("@@toPrimitive must return a primitive value."); } return ("string" === r ? String : Number)(t); }
+function _setFunctionName(e, t, n) { "symbol" == typeof t && (t = (t = t.description) ? "[" + t + "]" : ""); try { Object.defineProperty(e, "name", { configurable: !0, value: n ? n + " " + t : t }); } catch (e) {} return e; }
+function _checkInRHS(e) { if (Object(e) !== e) throw TypeError("right-hand side of 'in' should be an object, got " + (null !== e ? typeof e : "null")); return e; }
+import { Inject } from '@fluojs/core';
+import { MongooseConnection } from './connection.js';
 function isTransactionConnection(value) {
   return (typeof value === 'object' && value !== null || typeof value === 'function') && typeof value.transaction === 'function';
 }
@@ -62,4 +70,38 @@ export function Transaction(accessor) {
       return connection.transaction(() => value.apply(this, args));
     };
   };
-}
+}
+
+/**
+ * Compatibility HTTP interceptor that opens a Mongoose request transaction around a routed handler.
+ *
+ * @remarks
+ * This deprecated 1.x bridge forwards the request `AbortSignal` to `MongooseConnection.requestTransaction(...)`.
+ * Prefer service-layer `@Transaction()` or an explicit request boundary for new code.
+ *
+ * @deprecated Prefer service-layer `@Transaction()` or explicit `MongooseConnection.requestTransaction(...)`.
+ */
+let _MongooseTransactionI;
+class MongooseTransactionInterceptor {
+  static {
+    [_MongooseTransactionI, _initClass] = _applyDecs(this, [Inject(MongooseConnection)], []).c;
+  }
+  constructor(connection) {
+    this.connection = connection;
+  }
+
+  /**
+   * Runs the downstream handler inside the compatibility request transaction.
+   *
+   * @param context Interceptor context containing the request cancellation signal.
+   * @param next Downstream handler chain.
+   * @returns The downstream result after the request transaction settles.
+   */
+  async intercept(context, next) {
+    return this.connection.requestTransaction(() => next.handle(), context.requestContext.request.signal);
+  }
+  static {
+    _initClass();
+  }
+}
+export { _MongooseTransactionI as MongooseTransactionInterceptor };

package/dist/types.d.ts

@@ -1,9 +1,10 @@
 import type { MaybePromise } from '@fluojs/core';
 /**
- * Minimal Mongoose connection seam that optionally supports session creation.
+ * Minimal Mongoose connection seam that optionally supports session transaction APIs.
  *
  * @remarks
- * Fluo only requires `startSession()` to expose transaction helpers; plain connection usage still works without it.
+ * Fluo can open transaction helpers through either `connection.transaction(...)` or `startSession()`;
+ * plain connection usage still works without either API.
  */
 export interface MongooseConnectionLike {
     startSession?(): Promise<MongooseSessionLike>;
@@ -18,6 +19,32 @@ export interface MongooseSessionLike {
     abortTransaction(): MaybePromise<void>;
     endSession(): MaybePromise<void>;
 }
+/**
+ * Callable model facade returned by `MongooseConnection.model(...)`.
+ *
+ * @remarks
+ * The listed operations receive the ambient transaction session automatically when called inside a transaction boundary.
+ * Other model properties remain available as `unknown` because fluo does not own application schema or plugin typing.
+ *
+ * @typeParam TCreateResult Result returned by `create(...)`.
+ * @typeParam TFindResult Result returned by `find(...)`.
+ * @typeParam TFindOneResult Result returned by `findOne(...)`.
+ * @typeParam TAggregateResult Result returned by `aggregate(...)`.
+ * @typeParam TBulkWriteResult Result returned by `bulkWrite(...)`.
+ */
+export interface MongooseModelFacade<TCreateResult = unknown, TFindResult = unknown, TFindOneResult = unknown, TAggregateResult = unknown, TBulkWriteResult = unknown> {
+    /** Runs a Mongoose aggregate operation with ambient session options. */
+    aggregate(...args: unknown[]): TAggregateResult;
+    /** Runs a Mongoose bulk-write operation with ambient session options. */
+    bulkWrite(...args: unknown[]): TBulkWriteResult;
+    /** Runs a Mongoose create operation with ambient session options. */
+    create(...args: unknown[]): TCreateResult;
+    /** Runs a Mongoose find operation with ambient session options. */
+    find(...args: unknown[]): TFindResult;
+    /** Runs a Mongoose find-one operation with ambient session options. */
+    findOne(...args: unknown[]): TFindOneResult;
+    readonly [key: PropertyKey]: unknown;
+}
 /**
  * Module options for registering a Mongoose connection and optional shutdown disposal hook.
  *
@@ -31,7 +58,8 @@ export interface MongooseModuleOptions<TConnection extends MongooseConnectionLik
     /** Whether Mongoose providers should be visible globally. Defaults to `false`. */
     global?: boolean;
     /**
-     * Throws when transaction helpers are used against a connection that does not implement `startSession()`.
+     * Throws when transaction helpers are used against a connection that implements neither `connection.transaction(...)` nor
+     * `startSession()`.
      *
      * @remarks
      * Leave this disabled when `transaction()` / `requestTransaction()` should fall back to direct execution.
@@ -55,7 +83,7 @@ export interface MongooseHandleProvider<TConnection extends MongooseConnectionLi
      * @param args Additional model resolver arguments forwarded unchanged.
      * @returns The root model outside transactions, or a model facade inside an active transaction boundary.
      */
-    model(name: string, ...args: unknown[]): Record<PropertyKey, unknown>;
+    model<TModel extends MongooseModelFacade = MongooseModelFacade>(name: string, ...args: unknown[]): TModel;
     /**
      * Opens a Mongoose session transaction boundary around `fn`.
      *

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAEjD;;;;;GAKG;AACH,MAAM,WAAW,sBAAsB;IACrC,YAAY,CAAC,IAAI,OAAO,CAAC,mBAAmB,CAAC,CAAC;IAC9C,WAAW,CAAC,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,OAAO,EAAE,mBAAmB,KAAK,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;CAC/E;AAED;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,gBAAgB,IAAI,YAAY,CAAC,IAAI,CAAC,CAAC;IACvC,iBAAiB,IAAI,YAAY,CAAC,IAAI,CAAC,CAAC;IACxC,gBAAgB,IAAI,YAAY,CAAC,IAAI,CAAC,CAAC;IACvC,UAAU,IAAI,YAAY,CAAC,IAAI,CAAC,CAAC;CAClC;AAED;;;;GAIG;AACH,MAAM,WAAW,qBAAqB,CAAC,WAAW,SAAS,sBAAsB,GAAG,sBAAsB;IACxG,kFAAkF;IAClF,UAAU,EAAE,WAAW,CAAC;IACxB,2FAA2F;IAC3F,OAAO,CAAC,EAAE,CAAC,UAAU,EAAE,WAAW,KAAK,YAAY,CAAC,IAAI,CAAC,CAAC;IAC1D,kFAAkF;IAClF,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB;;;;;OAKG;IACH,kBAAkB,CAAC,EAAE,OAAO,CAAC;CAC9B;AAED;;;;GAIG;AACH,MAAM,WAAW,sBAAsB,CAAC,WAAW,SAAS,sBAAsB,GAAG,sBAAsB;IACzG,uFAAuF;IACvF,OAAO,IAAI,WAAW,CAAC;IACvB,2FAA2F;IAC3F,cAAc,IAAI,mBAAmB,GAAG,SAAS,CAAC;IAClD;;;;;;OAMG;IACH,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,MAAM,CAAC,WAAW,EAAE,OAAO,CAAC,CAAC;IACtE;;;;;OAKG;IACH,WAAW,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;IACjD;;;;;;OAMG;IACH,kBAAkB,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;CAC/E"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAEjD;;;;;;GAMG;AACH,MAAM,WAAW,sBAAsB;IACrC,YAAY,CAAC,IAAI,OAAO,CAAC,mBAAmB,CAAC,CAAC;IAC9C,WAAW,CAAC,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,OAAO,EAAE,mBAAmB,KAAK,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;CAC/E;AAED;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,gBAAgB,IAAI,YAAY,CAAC,IAAI,CAAC,CAAC;IACvC,iBAAiB,IAAI,YAAY,CAAC,IAAI,CAAC,CAAC;IACxC,gBAAgB,IAAI,YAAY,CAAC,IAAI,CAAC,CAAC;IACvC,UAAU,IAAI,YAAY,CAAC,IAAI,CAAC,CAAC;CAClC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,mBAAmB,CAClC,aAAa,GAAG,OAAO,EACvB,WAAW,GAAG,OAAO,EACrB,cAAc,GAAG,OAAO,EACxB,gBAAgB,GAAG,OAAO,EAC1B,gBAAgB,GAAG,OAAO;IAE1B,wEAAwE;IACxE,SAAS,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,gBAAgB,CAAC;IAChD,yEAAyE;IACzE,SAAS,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,gBAAgB,CAAC;IAChD,qEAAqE;IACrE,MAAM,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,aAAa,CAAC;IAC1C,mEAAmE;IACnE,IAAI,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,WAAW,CAAC;IACtC,uEAAuE;IACvE,OAAO,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,cAAc,CAAC;IAC5C,QAAQ,EAAE,GAAG,EAAE,WAAW,GAAG,OAAO,CAAC;CACtC;AAED;;;;GAIG;AACH,MAAM,WAAW,qBAAqB,CAAC,WAAW,SAAS,sBAAsB,GAAG,sBAAsB;IACxG,kFAAkF;IAClF,UAAU,EAAE,WAAW,CAAC;IACxB,2FAA2F;IAC3F,OAAO,CAAC,EAAE,CAAC,UAAU,EAAE,WAAW,KAAK,YAAY,CAAC,IAAI,CAAC,CAAC;IAC1D,kFAAkF;IAClF,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB;;;;;;OAMG;IACH,kBAAkB,CAAC,EAAE,OAAO,CAAC;CAC9B;AAED;;;;GAIG;AACH,MAAM,WAAW,sBAAsB,CAAC,WAAW,SAAS,sBAAsB,GAAG,sBAAsB;IACzG,uFAAuF;IACvF,OAAO,IAAI,WAAW,CAAC;IACvB,2FAA2F;IAC3F,cAAc,IAAI,mBAAmB,GAAG,SAAS,CAAC;IAClD;;;;;;OAMG;IACH,KAAK,CAAC,MAAM,SAAS,mBAAmB,GAAG,mBAAmB,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,MAAM,CAAC;IAC1G;;;;;OAKG;IACH,WAAW,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;IACjD;;;;;;OAMG;IACH,kBAAkB,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;CAC/E"}

package/package.json

@@ -9,7 +9,7 @@
     "transaction",
     "odm"
   ],
-  "version": "1.1.0",
+  "version": "2.0.0",
   "private": false,
   "license": "MIT",
   "repository": {
@@ -18,7 +18,7 @@
     "directory": "packages/mongoose"
   },
   "engines": {
-    "node": ">=20.0.0"
+    "node": ">=24.0.0 <27"
   },
   "publishConfig": {
     "access": "public"
@@ -36,10 +36,10 @@
     "dist"
   ],
   "dependencies": {
-    "@fluojs/core": "^1.0.3",
-    "@fluojs/http": "^1.1.2",
-    "@fluojs/di": "^1.1.0",
-    "@fluojs/runtime": "^1.1.8"
+    "@fluojs/core": "^2.0.0",
+    "@fluojs/http": "^3.0.0",
+    "@fluojs/di": "^3.0.0",
+    "@fluojs/runtime": "^3.0.0"
   },
   "peerDependencies": {
     "mongoose": ">=7.0.0"
@@ -50,7 +50,7 @@
     }
   },
   "devDependencies": {
-    "vitest": "^3.2.4"
+    "vitest": "^4.1.11"
   },
   "scripts": {
     "prebuild": "node ../../tooling/scripts/clean-dist.mjs",