@bleedingdev/modern-js-main-doc 3.4.0-ultramodern.19 → 3.4.0-ultramodern.20

package/docs/en/configure/app/bff/effect.mdx

@@ -9,6 +9,7 @@ title: effect
 ```ts
 type BffEffectUserConfig = {
   entry?: string;
+  strictEffectApproach?: true;
   openapi?: boolean | { path?: string };
   dataPlatform?: {
     enabled?: boolean;
@@ -58,7 +59,7 @@ For Effect v4, TypeScript should use export-map aware module resolution.
 ## bff.effect.entry
 
 - **Type:** `string`
-- **Default:** `<apiDirectory>/effect/index`
+- **Default:** `<apiDirectory>/index`
 
 Specifies the entry module for Effect HttpApi runtime.
 
@@ -67,12 +68,19 @@ export default defineConfig({
   bff: {
     runtimeFramework: 'effect',
     effect: {
-      entry: './api/effect/index',
+      entry: './api/index',
     },
   },
 });
 ```
 
+## bff.effect.strictEffectApproach
+
+- **Type:** `true`
+- **Default:** `true`
+
+Effect BFF modules must expose the strict Effect API surface (`defineEffectBff(...)` or `{ api, layer }`) and raw request handlers are rejected. Generated UltraModern apps write this marker explicitly.
+
 ## bff.effect.openapi
 
 - **Type:** `boolean | { path?: string }`
@@ -173,4 +181,4 @@ export default defineConfig({
 
 `batch.flushIntervalMs` controls the client-side micro-batch window in the generated Effect client. `maxConcurrency` and `requestTimeoutMs` are applied by the server batch gateway when dispatching items.
 
-The generated `effectBff.client.*` API only exists for loader-materialized `@api/effect/*` imports. Directly importing the server entry (`api/effect/index`) exposes the Effect BFF definition; its `client` property is a placeholder that fails on operation access.
+The generated `api.client.*` API only exists for loader-materialized `@api/index` imports. Directly importing the server entry (`api/index`) exposes the Effect BFF definition; its `client` property is a placeholder that fails on operation access.

package/docs/en/configure/app/bff/runtime-framework.mdx

@@ -21,8 +21,8 @@ export default defineConfig({
 });
 ```
 
-- Set to `'effect'` to run BFF only from `api/effect/index` (Effect HttpApi runtime).
+- Set to `'effect'` to run BFF only from `api/index` (Effect HttpApi runtime).
 - Set to `'hono'` to run BFF only from file-convention handlers under `api/lambda/**`.
 
 There is no implicit fallback between runtimes. Choose one runtime mode per app.
-Generated UltraModern apps use the Effect lane by default; set `runtimeFramework: 'hono'` only for the compatibility runtime.
+Generated UltraModern apps use strict Effect APIs by default and set `bff.effect.strictEffectApproach: true`.

package/docs/en/guides/advanced-features/bff/data-platform.mdx

@@ -4,7 +4,7 @@ title: Data Platform
 
 # Data Platform
 
-Modern.js Effect BFF now supports a request-envelope based data platform contract for safer and more predictable data orchestration in complex applications such as Module Federation and micro frontends.
+Modern.js Effect API runtime now supports a request-envelope based data platform contract for safer and more predictable data orchestration in complex applications such as Module Federation and micro frontends.
 
 ## What it solves
 
@@ -57,11 +57,11 @@ export default defineConfig({
 
 Envelope validation is enabled by default but does not require an envelope unless `requireEnvelope` is set. Origin validation is enabled by default; set `validateOrigin: false` to skip comparing the envelope origin against the incoming `Origin` header, or the request URL origin when the header is absent.
 
-## Generated Effect client behavior
+## Generated API client behavior
 
-When using the generated Effect client (`@api/effect/index`), Modern.js automatically attaches a serialized data envelope header (`x-modernjs-data-envelope`) for same-origin requests.
+When using the generated API client (`@api/index`), Modern.js automatically attaches a serialized data envelope header (`x-modernjs-data-envelope`) for same-origin requests.
 
-The generated client is loader-materialized. Import it from `@api/effect/*` in browser or client-bundled code; direct imports of the server entry (`api/effect/index`) expose the Effect BFF definition and only provide a placeholder `client`.
+The generated client is loader-materialized. Import it from `@api/index` in browser or client-bundled code; direct imports of the server entry (`api/index`) expose the Effect API definition and only provide a placeholder `client`.
 
 The envelope includes:
 

package/docs/en/guides/advanced-features/bff/frameworks.mdx

@@ -7,7 +7,7 @@ title: Runtime Framework
 
 Modern.js supports two BFF runtime frameworks:
 
-- `effect` (default): use [Effect HttpApi](https://effect.website/) runtime from `api/effect/index`.
+- `effect` (default): use [Effect HttpApi](https://effect.website/) runtime from `api/index`.
 - `hono`: use file-convention BFF handlers from `api/lambda/**`.
 
 `effect` and `hono` are strict runtime modes. There is no automatic fallback between them.
@@ -23,6 +23,8 @@ export default defineConfig({
   bff: {
     runtimeFramework: 'effect',
     effect: {
+      entry: './api/index',
+      strictEffectApproach: true,
       openapi: {
         path: '/openapi.json',
       },
@@ -33,7 +35,7 @@ export default defineConfig({
 
 Define a shared Effect HttpApi contract (for type-safe client + server):
 
-```ts title="shared/effect/api.ts"
+```ts title="shared/api.ts"
 import {
   HttpApi,
   HttpApiEndpoint,
@@ -41,18 +43,18 @@ import {
   Schema,
 } from '@modern-js/plugin-bff/effect-client';
 
-export const bffEffectApi = HttpApi.make('MyApi').add(
+export const bffApi = HttpApi.make('MyApi').add(
   HttpApiGroup.make('hello').add(
-    HttpApiEndpoint.get('ping', '/effect/ping', {
+    HttpApiEndpoint.get('ping', '/ping', {
       success: Schema.String,
     }),
   ),
 );
 ```
 
-Implement your Effect BFF entry at `api/effect/index.ts`:
+Implement your Effect API entry at `api/index.ts`:
 
-```ts title="api/effect/index.ts"
+```ts title="api/index.ts"
 import {
   Schema,
   Effect,
@@ -61,7 +63,7 @@ import {
   Layer,
   ServiceMap,
 } from '@modern-js/plugin-bff/effect-server';
-import { bffEffectApi } from '../../shared/effect/api';
+import { bffApi } from '../shared/api';
 
 class GreetingUnavailableError extends Schema.TaggedError<GreetingUnavailableError>()(
   'GreetingUnavailableError',
@@ -87,7 +89,7 @@ class GreetingService extends ServiceMap.Service<GreetingService>()('GreetingSer
   static readonly layer = Layer.effect(this, this.make);
 }
 
-const group = HttpApiBuilder.group(bffEffectApi, 'hello', handlers =>
+const group = HttpApiBuilder.group(bffApi, 'hello', handlers =>
   handlers.handle('ping', () =>
     GreetingService.use(service => service.hello()).pipe(
       Effect.catchTag('GreetingUnavailableError', error =>
@@ -97,23 +99,23 @@ const group = HttpApiBuilder.group(bffEffectApi, 'hello', handlers =>
   ),
 );
 
-const layer = HttpApiBuilder.layer(bffEffectApi).pipe(
+const layer = HttpApiBuilder.layer(bffApi).pipe(
   Layer.provide(group),
   Layer.provide(GreetingService.layer),
 );
 
-export default defineEffectBff({ api: bffEffectApi, layer });
+export default defineEffectBff({ api: bffApi, layer });
 ```
 
-Call Effect endpoints from browser code via `@api/effect/index`:
+Call Effect endpoints from browser code via `@api/index`:
 
 ```ts title="src/routes/page.tsx"
-import effectBff from '@api/effect/index';
+import api from '@api/index';
 
-const response = await effectBff.client.hello.ping({});
+const response = await api.client.hello.ping({});
 ```
 
-The `effectBff.client.*` surface is materialized by the BFF loader for `@api/effect/*` imports. Do not import `api/effect/index` directly and expect `client` to run in server code, scripts, or tests; direct entry imports expose the server runtime definition, and `client` is only a typed placeholder there.
+The `api.client.*` surface is materialized by the BFF loader for `@api/index` imports. Do not import `api/index` directly and expect `client` to run in server code, scripts, or tests; direct entry imports expose the server runtime definition, and `client` is only a typed placeholder there.
 
 import Hono from '@site-docs-en/components/hono';
 

package/docs/en/guides/advanced-features/bff/function.mdx

@@ -2,6 +2,10 @@
 
 In a Modern.js application, developers can define API files under the `api/lambda` directory and export API functions from these files. In the frontend code, these API functions can be directly invoked by importing the file, which initiates the API requests.
 
+:::warning
+`api/lambda/**` is the Hono/file-function compatibility runtime. New UltraModern generated API work should use the strict Effect runtime with `api/index.ts`, `shared/api.ts`, `defineEffectBff(...)`, and Effect `HttpApi` schemas instead.
+:::
+
 This invocation method is called **unified invocation**, where developers do not need to write glue code for the frontend and backend separately, thereby ensuring type safety across both.
 
 ## Enable BFF

package/docs/en/guides/get-started/ultramodern.mdx

@@ -33,7 +33,7 @@ UltraModern.js additions are designed as the default product surface for new Sup
 | Build diagnostics | RsDoctor is generally opt-in | Adds a first-class `performance.rsdoctor` config surface (opt-in; the earlier default-on behavior and diagnostics contract artifact were reverted) |
 | Output and static serving | Precompression behavior is app-defined | Enables `output.precompress` by default and serves `.br` / `.gz` variants via `Accept-Encoding` negotiation |
 | BFF runtime and contracts | Standard BFF runtime/client generation | Adds `requestId`-aware producer isolation, fail-fast initialization checks, and operation/trace correlation headers |
-| BFF runtime choices | Hono runtime path only in Modern.js 3.0 baseline (no built-in Effect runtime path) | Sets Effect as default runtime, enforces strict runtime split (`effect` -> `api/effect`, `hono` -> `api/lambda`), and adds Effect-Schema-first contracts plus MF failure-injection reliability coverage |
+| BFF runtime choices | Hono runtime path only in Modern.js 3.0 baseline (no built-in Effect runtime path) | Sets Effect as the strict default API runtime (`api/index.ts`, `shared/api.ts`, `src/api/*`) and keeps raw Hono handlers as an explicit compatibility lane |
 | Telemetry standardization | Observability wiring is often app-specific | Adds framework-level telemetry pipeline with OTLP/VictoriaMetrics exporters, redaction, batching, and backpressure controls |
 | App-level MF SSR handshake | No dedicated super-app app-level stability contract focus | Adds `server.ssr.moduleFederationAppSSR` plus integration-tested env/config handshake |
 | MF vertical loading reliability | Retry/fallback patterns are often implemented per app | Adds deterministic timeout/network/contract-error reliability matrix and distributed OTEL continuity tests |
@@ -46,16 +46,16 @@ UltraModern.js additions are designed as the default product surface for new Sup
 
 - We do not hide the fork behind legacy Modern.js branding.
 - We do not optimize for generic Modern.js defaults when they conflict with SuperApp reliability.
-- We keep both runtime modes (`effect`, `hono`) as explicit choices and avoid implicit fallback between them.
-- We avoid incompatible API changes unless there is a hard reliability requirement.
+- Generated UltraModern API work uses the Effect runtime only; raw Hono/function handlers are not part of the generated API architecture.
+- We make incompatible scaffold changes when they remove architecture drift.
 
 ## Migration Guide
 
-For teams already on Modern.js 3.0 or an older BleedingDev UltraModern scaffold, the adoption path remains compatibility-aware: keep the pieces that reduce risk, move toward MV-first / TanStack-first / Effect-first defaults, and keep fallback lanes explicit while you adopt UltraModern.js 3.0 as a separate framework.
+For teams already on Modern.js 3.0 or an older BleedingDev UltraModern scaffold, the adoption path is to move API work onto the strict Effect API surface instead of preserving older raw handler layouts.
 
 1. Keep existing React Router apps running as-is. TanStack Router is the preferred path for new scaffolds and incremental route adoption, but the React Router lane remains supported while teams move on their own schedule.
-2. Prefer `bff.runtimeFramework: 'effect'` for new BFF work, with the entry implemented at `api/effect/index.ts`. If your app already uses Hono handlers under `api/lambda/**`, keep `bff.runtimeFramework: 'hono'` until you are ready to move them; Hono remains a supported compatibility lane.
-3. Treat the baseline contracts as progressive defaults, not a forced cutover. `MODERN_BASELINE_ENABLE_MF_SSR`, `MODERN_BASELINE_ENABLE_BFF_REQUEST_ID`, and `MODERN_BASELINE_ENABLE_TELEMETRY_EXPORTERS` already let each app opt out while it converges on the preferred stack.
+2. Use `bff.runtimeFramework: 'effect'` with `bff.effect.strictEffectApproach: true` for API work. Entries live at `api/index.ts`, contracts live at `shared/api.ts`, clients live under `src/api/*`, and request/response/error shapes come from Effect `Schema` plus `HttpApi`.
+3. Treat raw handlers, `api/lambda/**`, manual `Response` construction, and manual request parsing as migration defects in generated UltraModern workspaces.
 4. The public preset now ships with explicit release and certification gates. Generated workspaces include `.github/workflows/ultramodern-workspace-gates.yml`, so `pnpm check` and `pnpm build` stay part of the local adoption contract from day one while CI runs the primitive gates as parallel matrix jobs.
 
 For an older generated workspace, migrate by treating the published cohort as
@@ -71,14 +71,49 @@ mise exec -- pnpm check
 mise exec -- pnpm build
 ```
 
+Strict Effect API migration is not compatible with
+`3.4.0-ultramodern.19` or older package cohorts. Those packages do not include
+the `strictEffectApproach` config type or the direct `api/index.ts`
+generator/checks. Until a newer BleedingDev cohort is published, use the local
+Modern.js workspace for migration validation; after publication, pin that exact
+new cohort with `--ultramodern-package-version`.
+
+When migrating a generated workspace that already has Effect API files, make the
+move explicit and do not keep compatibility aliases:
+
+1. Move each vertical server entry from `verticals/<id>/api/effect/index.ts` to
+   `verticals/<id>/api/index.ts`.
+2. Move each shared API contract from `verticals/<id>/shared/effect/api.ts` to
+   `verticals/<id>/shared/api.ts`.
+3. Move generated clients from `verticals/<id>/src/effect/*-client.ts` to
+   `verticals/<id>/src/api/*-client.ts`.
+4. Move shell API aggregates from `apps/shell-super-app/src/effect/*` to
+   `apps/shell-super-app/src/api/*`.
+5. Update imports and package exports to use `./api`, `./api/client`, and
+   `@<workspace>/<vertical>/api/client`; remove `./effect/client`,
+   `./shared/effect/api`, and shared Effect API packages.
+6. Update every vertical `modern.config.ts` to use
+   `bff.effect.entry: './api/index'` and
+   `bff.effect.strictEffectApproach: true`.
+7. Update topology so API metadata lives directly under `api` with
+   `api.bff.strictEffectApproach: true`; do not keep `api.effect`.
+8. Run `pnpm api:check`,
+   `scripts/validate-ultramodern-workspace.mjs`, `pnpm check`, and
+   `pnpm build`.
+
+If a migration fails, fix the owning generated contract, topology, package
+exports, or API module. Do not add app-level aliases, raw request handlers,
+manual `Response` construction, local type casts, or package shims to make the
+old layout pass.
+
 Use one package-source strategy per repo. The published BleedingDev create
 package defaults to `--ultramodern-package-source=install` and records the
-exact cohort in `.modernjs/ultramodern-package-source.json`. Keep `--workspace`
-only for local monorepo testing against unreleased packages. Release proof and
-CI should pin the exact cohort with `--ultramodern-package-version` when a
-repo must prove a specific published framework version.
+exact cohort in `.modernjs/ultramodern.json`. Keep `--workspace` only for local
+monorepo testing against unreleased packages. Release proof and CI should pin
+the exact cohort with `--ultramodern-package-version` when a repo must prove a
+specific published framework version.
 
-Older repos with Effect BFF entries and `verbatimModuleSyntax` should update to
+Older repos with nested Effect entries and `verbatimModuleSyntax` should update to
 the latest BleedingDev cohort instead of adding app-level `"type": "module"`
 metadata, Module Federation shims, or custom server wrappers. The framework BFF
 compiler normalizes CommonJS server output while generated app packages keep
@@ -239,8 +274,8 @@ non-indexable routes emit no JSON-LD by default. Public route owners can add
 `jsonLd` beside localized paths and use the generated
 `src/routes/ultramodern-jsonld.ts` helpers for common schema.org shapes.
 
-The generated contract writes `.modernjs/ultramodern-generated-contract.json`
-with a `cssFederation` section:
+The generated contract writes `.modernjs/ultramodern.json` with a
+`cssFederation` section:
 
 - `packages/shared-design-tokens` owns the shared token layer and exports `./tokens.css`.
 - Shell CSS owns only shell base and overlay layers under `[data-app-id="shell-super-app"]`.
@@ -248,7 +283,7 @@ with a `cssFederation` section:
 - Tailwind CSS v4 is local to each generated app through `@tailwindcss/postcss`; shared base styles must not be duplicated by verticals.
 - SSR first paint requires shared token CSS and app-owned CSS to be emitted by Modern/Rspack assets. Vertical CSS is loaded through manifest ownership, not copied into shell source.
 
-Version switching must select UI, Effect API, CSS, i18n JSON, and MF manifest evidence from the same vertical build marker. A shell render that only changes the UI marker is not enough.
+Version switching must select UI, API, CSS, i18n JSON, and MF manifest evidence from the same vertical build marker. A shell render that only changes the UI marker is not enough.
 
 ### Validation And Deploy
 

package/docs/zh/configure/app/bff/effect.mdx

@@ -9,6 +9,7 @@ title: effect
 ```ts
 type BffEffectUserConfig = {
   entry?: string;
+  strictEffectApproach?: true;
   openapi?: boolean | { path?: string };
   dataPlatform?: {
     enabled?: boolean;
@@ -58,7 +59,7 @@ import EnableBFFCaution from "@site-docs/components/enable-bff-caution";
 ## bff.effect.entry
 
 - **类型：** `string`
-- **默认值：** `<apiDirectory>/effect/index`
+- **默认值：** `<apiDirectory>/index`
 
 用于指定 Effect HttpApi 运行时入口模块。
 
@@ -67,12 +68,19 @@ export default defineConfig({
   bff: {
     runtimeFramework: 'effect',
     effect: {
-      entry: './api/effect/index',
+      entry: './api/index',
     },
   },
 });
 ```
 
+## bff.effect.strictEffectApproach
+
+- **类型：** `true`
+- **默认值：** `true`
+
+Effect BFF 模块必须导出严格 Effect API surface（`defineEffectBff(...)` 或 `{ api, layer }`），原始 request handler 会被拒绝。生成的 UltraModern 应用会显式写入这个标记。
+
 ## bff.effect.openapi
 
 - **类型：** `boolean | { path?: string }`
@@ -173,4 +181,4 @@ export default defineConfig({
 
 `batch.flushIntervalMs` 用于控制生成的 Effect 客户端微批处理窗口；`maxConcurrency` 与 `requestTimeoutMs` 由服务端批处理网关用于内部请求分发。
 
-生成的 `effectBff.client.*` API 只存在于 loader 物化后的 `@api/effect/*` 导入中。直接导入服务端入口（`api/effect/index`）时拿到的是 Effect BFF 定义；其中的 `client` 属性只是占位，并会在访问具体操作时报错。
+生成的 `api.client.*` API 只存在于 loader 物化后的 `@api/index` 导入中。直接导入服务端入口（`api/index`）时拿到的是 Effect BFF 定义；其中的 `client` 属性只是占位，并会在访问具体操作时报错。

package/docs/zh/configure/app/bff/runtime-framework.mdx

@@ -21,8 +21,8 @@ export default defineConfig({
 });
 ```
 
-- 设置为 `'effect'` 时，仅从 `api/effect/index` 运行 BFF（Effect HttpApi 运行时）。
+- 设置为 `'effect'` 时，仅从 `api/index` 运行 BFF（Effect HttpApi 运行时）。
 - 设置为 `'hono'` 时，仅从 `api/lambda/**` 的文件约定处理函数运行 BFF。
 
 两种运行时之间没有隐式回退，应用需要显式选择其一。
-生成的 UltraModern 应用默认使用 Effect 分支；仅在需要兼容运行时时设置 `runtimeFramework: 'hono'`。
+生成的 UltraModern 应用默认使用严格 Effect API，并设置 `bff.effect.strictEffectApproach: true`。

package/docs/zh/guides/advanced-features/bff/data-platform.mdx

@@ -59,9 +59,9 @@ Envelope 校验默认开启，但只有设置 `requireEnvelope` 时才强制要
 
 ## Effect 客户端自动行为
 
-使用生成的 Effect 客户端（`@api/effect/index`）时，Modern.js 会在同源请求中自动附加序列化的 envelope 请求头（`x-modernjs-data-envelope`）。
+使用生成的 Effect 客户端（`@api/index`）时，Modern.js 会在同源请求中自动附加序列化的 envelope 请求头（`x-modernjs-data-envelope`）。
 
-生成客户端由 loader 物化。请在浏览器或会被客户端打包的代码中通过 `@api/effect/*` 导入；直接导入服务端入口（`api/effect/index`）时拿到的是 Effect BFF 定义，其中只包含占位的 `client`。
+生成客户端由 loader 物化。请在浏览器或会被客户端打包的代码中通过 `@api/index` 导入；直接导入服务端入口（`api/index`）时拿到的是 Effect BFF 定义，其中只包含占位的 `client`。
 
 Envelope 默认包含：
 

package/docs/zh/guides/advanced-features/bff/frameworks.mdx

@@ -7,7 +7,7 @@ title: 运行时框架
 
 Modern.js 目前支持两种 BFF 运行时框架：
 
-- `effect`（默认）：使用 `api/effect/index` 的 [Effect HttpApi](https://effect.website/) 运行时。
+- `effect`（默认）：使用 `api/index` 的 [Effect HttpApi](https://effect.website/) 运行时。
 - `hono`：使用 `api/lambda/**` 的文件约定 BFF 处理函数。
 
 `effect` 与 `hono` 为严格模式，两者之间不会自动回退。
@@ -23,6 +23,8 @@ export default defineConfig({
   bff: {
     runtimeFramework: 'effect',
     effect: {
+      entry: './api/index',
+      strictEffectApproach: true,
       openapi: {
         path: '/openapi.json',
       },
@@ -33,7 +35,7 @@ export default defineConfig({
 
 先在共享目录中定义 Effect HttpApi 契约（前后端共享类型）：
 
-```ts title="shared/effect/api.ts"
+```ts title="shared/api.ts"
 import {
   HttpApi,
   HttpApiEndpoint,
@@ -41,18 +43,18 @@ import {
   Schema,
 } from '@modern-js/plugin-bff/effect-client';
 
-export const bffEffectApi = HttpApi.make('MyApi').add(
+export const bffApi = HttpApi.make('MyApi').add(
   HttpApiGroup.make('hello').add(
-    HttpApiEndpoint.get('ping', '/effect/ping', {
+    HttpApiEndpoint.get('ping', '/ping', {
       success: Schema.String,
     }),
   ),
 );
 ```
 
-然后在 `api/effect/index.ts` 中实现 Effect BFF 入口：
+然后在 `api/index.ts` 中实现 Effect BFF 入口：
 
-```ts title="api/effect/index.ts"
+```ts title="api/index.ts"
 import {
   Schema,
   Effect,
@@ -61,7 +63,7 @@ import {
   Layer,
   ServiceMap,
 } from '@modern-js/plugin-bff/effect-server';
-import { bffEffectApi } from '../../shared/effect/api';
+import { bffApi } from '../shared/api';
 
 class GreetingUnavailableError extends Schema.TaggedError<GreetingUnavailableError>()(
   'GreetingUnavailableError',
@@ -87,7 +89,7 @@ class GreetingService extends ServiceMap.Service<GreetingService>()('GreetingSer
   static readonly layer = Layer.effect(this, this.make);
 }
 
-const group = HttpApiBuilder.group(bffEffectApi, 'hello', handlers =>
+const group = HttpApiBuilder.group(bffApi, 'hello', handlers =>
   handlers.handle('ping', () =>
     GreetingService.use(service => service.hello()).pipe(
       Effect.catchTag('GreetingUnavailableError', error =>
@@ -97,23 +99,23 @@ const group = HttpApiBuilder.group(bffEffectApi, 'hello', handlers =>
   ),
 );
 
-const layer = HttpApiBuilder.layer(bffEffectApi).pipe(
+const layer = HttpApiBuilder.layer(bffApi).pipe(
   Layer.provide(group),
   Layer.provide(GreetingService.layer),
 );
 
-export default defineEffectBff({ api: bffEffectApi, layer });
+export default defineEffectBff({ api: bffApi, layer });
 ```
 
-在浏览器代码中通过 `@api/effect/index` 调用接口：
+在浏览器代码中通过 `@api/index` 调用接口：
 
 ```ts title="src/routes/page.tsx"
-import effectBff from '@api/effect/index';
+import api from '@api/index';
 
-const response = await effectBff.client.hello.ping({});
+const response = await api.client.hello.ping({});
 ```
 
-`effectBff.client.*` 由 BFF loader 针对 `@api/effect/*` 导入物化生成。不要直接导入 `api/effect/index` 并期望在服务端代码、脚本或测试中运行 `client`；直接导入入口时拿到的是服务端运行时定义，其中的 `client` 只是类型占位。
+`api.client.*` 由 BFF loader 针对 `@api/index` 导入物化生成。不要直接导入 `api/index` 并期望在服务端代码、脚本或测试中运行 `client`；直接导入入口时拿到的是服务端运行时定义，其中的 `client` 只是类型占位。
 
 import Hono from '@site-docs/components/hono';
 

package/docs/zh/guides/get-started/ultramodern.mdx

@@ -33,7 +33,7 @@ UltraModern.js 的增强能力是新 SuperApp 的默认产品面。兼容分支
 | 构建诊断能力 | RsDoctor 多为显式开启 | 新增一等的 `performance.rsdoctor` 配置项（按需开启；早期的默认开启行为与诊断契约产物已回退） |
 | 输出与静态资源回源 | 预压缩策略通常由业务自定义 | 默认开启 `output.precompress`，并按 `Accept-Encoding` 协商 `.br` / `.gz` 回源 |
 | BFF 运行时与契约 | 提供标准 BFF 运行时与客户端生成能力 | 增加 `requestId` 维度隔离、初始化 fail-fast 校验与操作/追踪关联 Header |
-| BFF 运行时选型 | Modern.js 3.0 基线仅提供 Hono 运行时路径（无内建 Effect 运行时） | 将 Effect 设为默认运行时，并采用严格运行时拆分（`effect` -> `api/effect`，`hono` -> `api/lambda`），同时补齐 Effect-Schema-first 契约与 MF failure-injection 覆盖 |
+| BFF 运行时选型 | Modern.js 3.0 基线仅提供 Hono 运行时路径（无内建 Effect 运行时） | 将 Effect HttpApi 设为默认 API surface，入口固定为 `api/index.ts`，共享契约固定为 `shared/api.ts`，并通过 `strictEffectApproach` 拒绝原始 request handler |
 | Telemetry 标准化 | 可观测链路通常由业务侧自行拼装 | 增加框架级 telemetry 管线，内置 OTLP/VictoriaMetrics，支持脱敏、批处理与背压 |
 | 应用级 MF SSR 协议 | 没有以 super-app 为重点的应用级稳定性契约开关 | 增加 `server.ssr.moduleFederationAppSSR` 配置/环境变量握手，并补齐集成级回归保障 |
 | MF vertical 加载可靠性 | 重试/降级策略通常由各业务单独实现 | 增加 timeout/network/contract-error 的确定性可靠性矩阵与分布式 OTEL 连续性断言 |
@@ -46,7 +46,7 @@ UltraModern.js 的增强能力是新 SuperApp 的默认产品面。兼容分支
 
 - 不再把这个 fork 隐藏在旧 Modern.js 品牌后面。
 - 当通用 Modern.js 默认值与 SuperApp 可靠性冲突时，不优先优化通用默认值。
-- 运行时保持 `effect` 与 `hono` 双模式并存，但不提供隐式回退。
+- 生成的 UltraModern API 只走严格 Effect surface；原始 request handler 和 Hono/file-function API 是显式非默认路径。
 - 除非稳定性硬需求，否则避免引入破坏性 API 变更。
 
 ## 迁移指南
@@ -54,7 +54,7 @@ UltraModern.js 的增强能力是新 SuperApp 的默认产品面。兼容分支
 对于已经在使用 Modern.js 3.0 或旧版 BleedingDev UltraModern scaffold 的团队，迁移路径是“兼容感知”：保留能降低风险的部分，逐步向 MV-first / TanStack-first / Effect-first 默认方向收敛，并把 UltraModern.js 3.0 作为独立框架采用。
 
 1. 既有 React Router 应用可以继续按现状运行。TanStack Router 是新脚手架与增量迁移的优先路径，但 React Router 兼容分支仍然保留，团队可以按自己的节奏迁移。
-2. 新建或迁移中的 BFF 能力优先使用 `bff.runtimeFramework: 'effect'`，并将入口实现放在 `api/effect/index.ts`。如果当前应用已经在 `api/lambda/**` 下使用 Hono 处理函数，就继续显式使用 `bff.runtimeFramework: 'hono'`，等准备好再迁移；Hono 仍是受支持的兼容分支。
+2. 新建或迁移中的 BFF 能力使用 `bff.runtimeFramework: 'effect'`、`bff.effect.entry: './api/index'` 和 `bff.effect.strictEffectApproach: true`。接口先改 `shared/api.ts` 的 `HttpApi` 契约，再在 `api/index.ts` 用 `defineEffectBff(...)` / `HttpApiBuilder` 实现。
 3. 将基线契约视为渐进式默认值，而不是一次性强制切换。`MODERN_BASELINE_ENABLE_MF_SSR`、`MODERN_BASELINE_ENABLE_BFF_REQUEST_ID` 和 `MODERN_BASELINE_ENABLE_TELEMETRY_EXPORTERS` 已经提供了按应用、按环境关闭的能力，方便在收敛到目标栈之前逐步过渡。
 4. 这套公开预设现在已经附带显式的发布 / 认证 gate。生成 workspace 会自带 `.github/workflows/ultramodern-workspace-gates.yml`，因此 `pnpm check` 与 `pnpm build` 从第一天开始就是本地接入契约的一部分；CI 会以并行矩阵运行这些基础 gate。
 
@@ -70,9 +70,40 @@ mise exec -- pnpm check
 mise exec -- pnpm build
 ```
 
+严格 Effect API 迁移不兼容 `3.4.0-ultramodern.19` 或更早的包 cohort。
+这些包还没有 `strictEffectApproach` 配置类型，也没有直接 `api/index.ts`
+的生成器和检查。新的 BleedingDev cohort 发布前，迁移校验应使用本地
+Modern.js workspace；发布后，用 `--ultramodern-package-version` 固定该新
+cohort。
+
+迁移已经带有 Effect API 文件的生成 workspace 时，明确移动文件，不保留兼容别名：
+
+1. 将每个 vertical 服务端入口从 `verticals/<id>/api/effect/index.ts` 移到
+   `verticals/<id>/api/index.ts`。
+2. 将每个共享 API 契约从 `verticals/<id>/shared/effect/api.ts` 移到
+   `verticals/<id>/shared/api.ts`。
+3. 将生成客户端从 `verticals/<id>/src/effect/*-client.ts` 移到
+   `verticals/<id>/src/api/*-client.ts`。
+4. 将 shell API 聚合从 `apps/shell-super-app/src/effect/*` 移到
+   `apps/shell-super-app/src/api/*`。
+5. 更新 imports 和 package exports，使用 `./api`、`./api/client` 与
+   `@<workspace>/<vertical>/api/client`；删除 `./effect/client`、
+   `./shared/effect/api` 和 shared Effect API 包。
+6. 更新每个 vertical 的 `modern.config.ts`，设置
+   `bff.effect.entry: './api/index'` 和
+   `bff.effect.strictEffectApproach: true`。
+7. 更新 topology，让 API metadata 直接位于 `api` 下，并设置
+   `api.bff.strictEffectApproach: true`；不要保留 `api.effect`。
+8. 运行 `pnpm api:check`、`scripts/validate-ultramodern-workspace.mjs`、
+   `pnpm check` 和 `pnpm build`。
+
+如果迁移失败，应修复归属的生成契约、topology、package exports 或 API 模块。
+不要添加 app 级 alias、原始 request handler、手写 `Response`、本地类型断言或包
+shim 来让旧布局通过。
+
 每个仓库只使用一种 package-source 策略。已发布的 BleedingDev create 包默认使用
 `--ultramodern-package-source=install`，并把精确 cohort 记录到
-`.modernjs/ultramodern-package-source.json`。`--workspace` 只用于本地 monorepo
+`.modernjs/ultramodern.json`。`--workspace` 只用于本地 monorepo
 联调未发布包。发布证明和 CI 如果需要证明某个已发布框架版本，应使用
 `--ultramodern-package-version` 固定精确 cohort。
 
@@ -82,7 +113,7 @@ Federation shim 或自定义 server wrapper。框架 BFF compiler 会把服务
 CommonJS，同时生成的 app package 继续为 Module Federation DTS 保留稳定的
 `typescript`，并使用固定的 `@typescript/native-preview` 工具链执行 TS-Go 检查。
 
-安装新 cohort 后，先运行生成的
+安装新 cohort 后，先运行生成的 `pnpm api:check` 与
 `scripts/validate-ultramodern-workspace.mjs` 契约校验，再接受人工改动。topology、
 ownership、package-source、本地 overlay、生成契约、Tailwind prefix 或 Module
 Federation 冲突，都应在对应归属文件中修复，不要手写补丁覆盖生成结果。
@@ -215,7 +246,7 @@ JSON-LD 是可选的路由 metadata，不会自动推断。私有路由和不可
 JSON-LD。公开路由 owner 可以在本地化路径旁显式添加 `jsonLd`，并使用生成的
 `src/routes/ultramodern-jsonld.ts` helper 编写常见 schema.org 结构。
 
-生成契约会在 `.modernjs/ultramodern-generated-contract.json` 中写入
+生成契约会在 `.modernjs/ultramodern.json` 中写入
 `cssFederation`：
 
 - `packages/shared-design-tokens` 拥有共享 token layer，并导出 `./tokens.css`。

package/package.json

@@ -19,14 +19,14 @@
     "modern.js",
     "ultramodern.js"
   ],
-  "version": "3.4.0-ultramodern.19",
+  "version": "3.4.0-ultramodern.20",
   "publishConfig": {
     "registry": "https://registry.npmjs.org/",
     "access": "public"
   },
   "dependencies": {
     "mermaid": "^11.15.0",
-    "@modern-js/sandpack-react": "npm:@bleedingdev/modern-js-sandpack-react@3.4.0-ultramodern.19"
+    "@modern-js/sandpack-react": "npm:@bleedingdev/modern-js-sandpack-react@3.4.0-ultramodern.20"
   },
   "devDependencies": {
     "@rsbuild/plugin-sass": "2.0.0",