@bleedingdev/modern-js-main-doc 3.9.0-ultramodern.2 → 3.9.0-ultramodern.21

package/docs/en/components/deploy-command.mdx

@@ -8,6 +8,7 @@ Usage: modern deploy [options]
 Options:
   -c --config <config>  Specify configuration file path, either relative or absolute
   -s --skip-build       Skip the build stage
+  --deploy-target <target>  Deploy target (node, vercel, netlify, ghPages, cloudflare); overrides deploy.target and MODERNJS_DEPLOY
   -h, --help            Display command help
 ```
 

package/docs/en/components/hono.mdx

@@ -21,7 +21,7 @@ For more details, refer to [useHonoContext](/apis/app/runtime/bff/use-backend-co
 When getting cookies in BFF functions, you need to get the request context through `useHonoContext`, then use `c.req.header('cookie')` to get the Cookie string and parse it manually:
 
 ```ts title="api/lambda/cookies.ts"
-import { Api, Get } from '@modern-js/plugin-bff/hono-server';
+import { Api, Get } from '@modern-js/plugin-bff/server';
 import { useHonoContext } from '@modern-js/server-runtime';
 
 // Helper function to parse Cookie string
@@ -64,7 +64,7 @@ The `c.req.cookie()` method does not exist in the current version. You need to u
 When using Hono as the runtime framework, you can define interfaces through [Api functions](/guides/advanced-features/bff/operators.html):
 
 ```ts title="api/lambda/user.ts"
-import { Api, Get, Query } from '@modern-js/plugin-bff/hono-server';
+import { Api, Get, Query } from '@modern-js/plugin-bff/server';
 import { z } from 'zod';
 
 const QuerySchema = z.object({
@@ -93,7 +93,7 @@ For more details about Api functions and operators, refer to [Creating Extensibl
 Hono supports a rich middleware ecosystem, and you can use middleware in BFF functions:
 
 ```ts title="api/lambda/user.ts"
-import { Api, Get, Middleware } from '@modern-js/plugin-bff/hono-server';
+import { Api, Get, Middleware } from '@modern-js/plugin-bff/server';
 
 export const getUser = Api(
   Get('/user'),

package/docs/en/components/init-app.mdx

@@ -71,11 +71,7 @@ Now, the project structure is as follows:
 ```
 
 The default workspace starts shell-only and installs the published BleedingDev
-package aliases:
-
-```bash
-pnpm dlx @bleedingdev/modern-js-ultramodern-create my-super-app
-```
+package aliases.
 
 From a generated SuperApp workspace, add a business MicroVertical in place:
 

package/docs/en/components/prerequisites.mdx

@@ -9,7 +9,7 @@ import NodeVersion from '@site-docs-en/components/nodeVersion.mdx';
 It is recommended to use [pnpm](https://pnpm.io/installation) to manage dependencies:
 
 ```bash
-mise use pnpm@11.24.0
+mise use pnpm@11.27.1
 ```
 
 :::note

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

@@ -47,21 +47,33 @@ import EnableBFFCaution from "@site-docs-en/components/enable-bff-caution";
 
 :::caution Install the Effect peers yourself
 `effect` and `@effect/opentelemetry` are **optional exact peer dependencies** of
-`@modern-js/plugin-bff`, not dependencies. The plugin no longer bundles a copy —
-Effect 4 derives `Context` / `Service` keys per module instance, so a bundled copy
-would give your app a second Effect identity. Before setting
-`runtimeFramework: 'effect'` or importing `@modern-js/plugin-bff/effect`,
-`/effect-server`, `/effect-edge` or `/effect-client`, install the exact cohort:
+`@modern-js/bff-effect`. Install them in the application so its API modules and
+the framework use the same Effect instance. Before setting
+`runtimeFramework: 'effect'` or importing `@modern-js/bff-effect/effect`,
+`/effect-edge` or `/effect-client`, install the exact cohort:
 
 ```bash
-pnpm add effect@4.0.0-rc.112 @effect/opentelemetry@4.0.0-rc.112
+pnpm add effect@4.0.0-rc.117 @effect/opentelemetry@4.0.0-rc.117
 ```
 
 The pin is exact because UltraModern ships Effect as one lockstep cohort. Apps
-using only `runtimeFramework: 'hono'` or the `./data-platform` lane need neither
-package.
+using only native `runtimeFramework: 'hono'` or
+`@modern-js/bff-effect/data-platform` need neither package.
 :::
 
+Use `bffPlugin` from `@modern-js/plugin-bff-build-extensions` to register the
+Effect runtime. It composes the native BFF plugin. Install
+`@modern-js/bff-effect` and `@modern-js/plugin-bff-extensions` from the same
+framework cohort as application production dependencies, so the adapter remains
+available after development dependencies are removed. The build plugin can be a
+development dependency. See the [runtime configuration example](/guides/advanced-features/bff/frameworks).
+
+Native `@modern-js/plugin-bff/server` exports Hono APIs. For Node Effect APIs,
+import framework helpers such as `defineEffectBff` from
+`@modern-js/bff-effect/effect` and namespaces from the corresponding `effect/*`
+modules. Worker handlers and worker request context use
+`@modern-js/bff-effect/effect-edge`.
+
 Generated UltraModern workspaces use this runtime as the only generated HTTP API
 path. The API contract lives at `shared/api.ts`, the server runtime lives at
 `api/index.ts`, clients live under `src/api/*-client.ts`, and generated checks
@@ -173,7 +185,6 @@ export default defineConfig({
     endpoint: '/_data/batch',
     maxBatchSize: 16,
     maxBatchBytes: 64 * 1024,
-    flushIntervalMs: 8,
     maxConcurrency: 4,
     requestTimeoutMs: 10000,
     allowedMethods: ['GET'],
@@ -207,9 +218,9 @@ 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.
+`maxConcurrency` and `requestTimeoutMs` control the server batch gateway. Native `HttpApiClient` calls send individual requests; they do not automatically batch requests.
 
-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.
+Import a shared `HttpApi` contract and pass it to `HttpApiClient.make` or `makeEffectHttpApiClient`. The client is fully type-inferred; `defineEffectBff` exposes server handlers and does not contain a client.
 
 ## Effect cohort
 
@@ -218,14 +229,10 @@ through `pnpm-workspace.yaml` overrides. For the current UltraModern cohort,
 generated apps use:
 
 ```yaml
-trustPolicyExclude:
-  - 'effect@4.0.0-rc.112'
-  - '@effect/opentelemetry@4.0.0-rc.112'
-
 overrides:
-  '@effect/opentelemetry': 4.0.0-rc.112
-  '@effect/vitest': 4.0.0-rc.112
-  effect: 4.0.0-rc.112
+  '@effect/opentelemetry': 4.0.0-rc.117
+  '@effect/vitest': 4.0.0-rc.117
+  effect: 4.0.0-rc.117
 ```
 
 Do not add a different direct `effect` version in an app package. A mismatched
@@ -233,10 +240,7 @@ Effect prerelease can fail while building layers or HTTP middleware because runt
 services come from different package instances. The strict 24-hour release-age
 gate applies to installed packages; the current cohort has no Effect age
 exemption, and override-only `@effect/vitest` is not an installed approval
-target. `trustPolicyExclude` is a separate policy:
-its exact `effect` and `@effect/opentelemetry` exceptions cover their
-trusted-publisher to provenance metadata transition and are not release-age
-approvals.
+target.
 
 ## Contract tests
 
@@ -244,7 +248,7 @@ Strict Effect APIs should test the declared `HttpApi` contract, not a raw
 request handler. Edge-compatible tests can use the framework helper:
 
 ```ts
-import { createEffectBffTestHandler } from '@modern-js/plugin-bff/effect-edge';
+import { createEffectBffTestHandler } from '@modern-js/bff-effect/effect-edge';
 import apiModule from '../api/index';
 
 const testApi = await createEffectBffTestHandler({
@@ -259,12 +263,9 @@ If you manually compose an Effect web handler in a low-level proof, provide the
 platform services explicitly:
 
 ```ts
-import {
-  HttpApiBuilder,
-  HttpRouter,
-  HttpServer,
-  Layer,
-} from '@modern-js/plugin-bff/effect-server';
+import * as Layer from 'effect/Layer';
+import { HttpRouter, HttpServer } from 'effect/unstable/http';
+import { HttpApiBuilder } from 'effect/unstable/httpapi';
 
 const handler = HttpRouter.toWebHandler(
   HttpApiBuilder.layer(api).pipe(
@@ -284,13 +285,10 @@ current Effect v4 beta cohort, `HttpRouter.middleware(...)` returns a `Layer`
 directly:
 
 ```ts
-import {
-  Effect,
-  HttpApiBuilder,
-  HttpMiddleware,
-  HttpRouter,
-  Layer,
-} from '@modern-js/plugin-bff/effect-server';
+import * as Effect from 'effect/Effect';
+import * as Layer from 'effect/Layer';
+import { HttpMiddleware, HttpRouter } from 'effect/unstable/http';
+import { HttpApiBuilder } from 'effect/unstable/httpapi';
 
 const corsLayer = HttpRouter.middleware(
   Effect.succeed(

package/docs/en/configure/app/source/react-compiler.mdx

@@ -11,6 +11,8 @@ Whether to enable [React Compiler](https://react.dev/learn/react-compiler). Reac
 
 Modern.js implements this capability based on the Rust-based React Compiler built into Rspack's `builtin:swc-loader` (equivalent to setting SWC's `jsc.transform.reactCompiler`), reusing Rspack's built-in SWC transform chain without introducing Babel.
 
+The compiler only runs for browser environments (`output.target: 'web'`). Server environments (`node`, the `web-worker` SSR worker and BFF code) render once per request and gain nothing from memoization, so they are never compiled.
+
 :::tip
 This option is disabled by default. It must be enabled explicitly for any React version, including React 19.
 :::

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

@@ -17,7 +17,7 @@ Modern.js Effect API runtime now supports a request-envelope based data platform
 
 ## Runtime contract helpers
 
-Use `@modern-js/plugin-bff/data-platform` helpers to build and validate contracts:
+Use `@modern-js/bff-effect/data-platform` helpers to build and validate contracts:
 
 ```ts
 import {
@@ -30,7 +30,7 @@ import {
   validateHydrationEnvelope,
   createInvalidationEvent,
   shouldApplyInvalidation,
-} from '@modern-js/plugin-bff/data-platform';
+} from '@modern-js/bff-effect/data-platform';
 ```
 
 ## Effect runtime validation

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

@@ -5,10 +5,10 @@ title: Runtime Framework
 
 # Runtime Framework
 
-Modern.js supports two BFF runtime frameworks:
+Modern.js and the UltraModern BFF extension provide two runtime frameworks:
 
-- `effect` (default): use [Effect HttpApi](https://effect.website/) runtime from `api/index`.
-- `hono`: use file-convention BFF handlers from `api/lambda/**`.
+- `hono` is the native plugin default and uses file-convention handlers from `api/lambda/**`.
+- `effect` is the UltraModern extension default and uses [Effect HttpApi](https://effect.website/) from `api/index`.
 
 `effect` and `hono` are strict runtime modes. There is no automatic fallback between them.
 
@@ -19,12 +19,18 @@ Generated UltraModern workspaces use strict Effect APIs: author HTTP APIs in
 
 ## Switch to Effect runtime
 
+Use the fork build plugin below. It includes the native BFF plugin and registers
+the Effect adapter. The application needs `@modern-js/bff-effect` and
+`@modern-js/plugin-bff-extensions` as production dependencies from the same
+framework cohort. Install the exact Effect peers described in
+[`bff.effect`](/configure/app/bff/effect).
+
 ```ts title="modern.config.ts"
-import { bffPlugin } from '@modern-js/plugin-bff';
-import { defineConfig } from '@modern-js/app-tools';
+import { bffPlugin } from '@modern-js/plugin-bff-build-extensions';
+import { appTools, defineConfig } from '@modern-js/app-tools';
 
 export default defineConfig({
-  plugins: [bffPlugin()],
+  plugins: [appTools(), bffPlugin()],
   bff: {
     runtimeFramework: 'effect',
     effect: {
@@ -46,7 +52,7 @@ import {
   HttpApiEndpoint,
   HttpApiGroup,
   Schema,
-} from '@modern-js/plugin-bff/effect-client';
+} from '@modern-js/bff-effect/effect-client';
 
 export const bffApi = HttpApi.make('MyApi').add(
   HttpApiGroup.make('hello').add(
@@ -60,14 +66,12 @@ export const bffApi = HttpApi.make('MyApi').add(
 Implement your Effect API entry at `api/index.ts`:
 
 ```ts title="api/index.ts"
-import {
-  Schema,
-  Effect,
-  HttpApiBuilder,
-  defineEffectBff,
-  Layer,
-  ServiceMap,
-} from '@modern-js/plugin-bff/effect-server';
+import { defineEffectBff } from '@modern-js/bff-effect/effect';
+import * as Context from 'effect/Context';
+import * as Effect from 'effect/Effect';
+import * as Layer from 'effect/Layer';
+import * as Schema from 'effect/Schema';
+import { HttpApiBuilder } from 'effect/unstable/httpapi';
 import { bffApi } from '../shared/api';
 
 class GreetingUnavailableError extends Schema.TaggedError<GreetingUnavailableError>()(
@@ -77,7 +81,7 @@ class GreetingUnavailableError extends Schema.TaggedError<GreetingUnavailableErr
   },
 ) {}
 
-class GreetingService extends ServiceMap.Service<GreetingService>()('GreetingService', {
+class GreetingService extends Context.Service<GreetingService>()('GreetingService', {
   make: Effect.succeed({
     hello: Effect.fn('GreetingService.hello')(function* () {
       if (Date.now() < 0) {
@@ -112,19 +116,27 @@ const layer = HttpApiBuilder.layer(bffApi).pipe(
 export default defineEffectBff({ api: bffApi, layer });
 ```
 
-Call Effect endpoints from browser code via `@api/index`:
+Create a native, fully inferred client from the shared contract:
 
 ```ts title="src/routes/page.tsx"
-import api from '@api/index';
+import { Effect, makeEffectHttpApiClient } from '@modern-js/bff-effect/effect-client';
+import { bffApi } from '../../shared/api';
 
-const response = await api.client.hello.ping({});
+const response = await Effect.runPromise(
+  makeEffectHttpApiClient(bffApi, { baseUrl: '/api' }).pipe(
+    Effect.flatMap(client => client.hello.ping({})),
+  ),
+);
 ```
 
-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.
+Requests, responses, and declared errors are inferred from `bffApi`. No client generation or server-entry import is needed.
 
 For UltraModern, Effect `HttpApi` plus Effect BFF is the single blessed authored HTTP path. Use `HttpApi` endpoints with `query`, `params`, `payload`, `success`, and declared errors such as `HttpApiSchema.status(...)`; implement them with `HttpApiBuilder.group(...).handle(...)` and `HttpApiBuilder.layer(...).pipe(Layer.provide(...))`, then default-export the entry as `defineEffectBff({ api, layer })`. See `packages/server/bff-effect/tests/effect-edge-runtime.test.ts` for the live runtime shape.
 
-Hono and `api/lambda/**` are internal compatibility only and feature-frozen.
+Native Hono applications import operators from `@modern-js/plugin-bff/server`.
+UltraModern-generated applications keep their strict Effect API model. Worker
+handlers use `@modern-js/bff-effect/effect-edge`, including its worker request
+context exports; Node handlers use the Effect entry shown above.
 
 import Hono from '@site-docs-en/components/hono';
 

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

@@ -191,7 +191,7 @@ Parameters following the dynamic path are an object called `RequestOption`, whic
 In a standard function without dynamic routes, `RequestOption` can be obtained from the first parameter, for example:
 
 ```ts title="api/lambda/hello.ts"
-import type { RequestOption } from '@modern-js/plugin-bff/hono-server';
+import type { RequestOption } from '@modern-js/plugin-bff/server';
 
 export async function post({
   query,
@@ -204,7 +204,7 @@ export async function post({
 Custom types can also be used here:
 
 ```ts title="api/lambda/hello.ts"
-import type { RequestOption } from '@modern-js/plugin-bff/hono-server';
+import type { RequestOption } from '@modern-js/plugin-bff/server';
 
 type IQuery = {
   // some types

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

@@ -36,7 +36,7 @@ import BFFOperatorCode from '@site-docs/components/bff-operator-code';
 <BFFOperatorCode>
 
 ```typescript title="api/lambda/user.ts"
-import { Api, Post, Query, Data } from '@modern-js/plugin-bff/hono-server';
+import { Api, Post, Query, Data } from '@modern-js/plugin-bff/server';
 import { z } from 'zod';
 
 const UserSchema = z.object({
@@ -89,7 +89,7 @@ As shown in the example below, you can specify the route and HTTP Method through
 <BFFOperatorCode>
 
 ```typescript title="api/lambda/user.ts"
-import { Api, Get, Query, Data } from '@modern-js/plugin-bff/hono-server';
+import { Api, Get, Query, Data } from '@modern-js/plugin-bff/server';
 
 // Specify the interface route, Modern.js sets `bff.prefix` to `/api` by default,
 // so the interface route is `/api/user`, and the HTTP Method is GET.
@@ -107,7 +107,7 @@ When the route is not specified, the interface route is defined according to the
 <BFFOperatorCode>
 
 ```typescript title="api/lambda/user.ts"
-import { Api, Get, Query, Data } from '@modern-js/plugin-bff/hono-server';
+import { Api, Get, Query, Data } from '@modern-js/plugin-bff/server';
 
 // No interface route specified, according to file convention and function name, the interface is api/user, HTTP Method is get.
 export const get = Api(Query(UserSchema), async ({ query }) => query);
@@ -144,7 +144,7 @@ Using the `Query` function, you can define the type of query. After using the `Q
 
 ```typescript title="api/lambda/user.ts"
 // Server-side code
-import { Api, Query } from '@modern-js/plugin-bff/hono-server';
+import { Api, Query } from '@modern-js/plugin-bff/server';
 import { z } from 'zod';
 
 const UserSchema = z.object({
@@ -176,7 +176,7 @@ URL query parameters are strings by default. If you need numeric types, you need
 <BFFOperatorCode>
 
 ```typescript title="api/lambda/user.ts"
-import { Api, Get, Query } from '@modern-js/plugin-bff/hono-server';
+import { Api, Get, Query } from '@modern-js/plugin-bff/server';
 import { z } from 'zod';
 
 const QuerySchema = z.object({
@@ -216,7 +216,7 @@ If you use the Data function, you must follow the HTTP protocol. When the HTTP M
 <BFFOperatorCode>
 
 ```typescript title="api/lambda/user.ts"
-import { Api, Data } from '@modern-js/plugin-bff/hono-server';
+import { Api, Data } from '@modern-js/plugin-bff/server';
 import { z } from 'zod';
 
 const DataSchema = z.object({
@@ -249,7 +249,7 @@ Route parameters can implement dynamic routes and get parameters from the path.
 <BFFOperatorCode>
 
 ```typescript
-import { Api, Get, Params } from '@modern-js/plugin-bff/hono-server';
+import { Api, Get, Params } from '@modern-js/plugin-bff/server';
 import { z } from 'zod';
 
 const UserSchema = z.object({
@@ -274,7 +274,7 @@ You can define the request headers required by the interface through the `Header
 <BFFOperatorCode>
 
 ```typescript
-import { Api, Headers } from '@modern-js/plugin-bff/hono-server';
+import { Api, Headers } from '@modern-js/plugin-bff/server';
 import { z } from 'zod';
 
 const headerSchema = z.object({
@@ -336,7 +336,7 @@ The `Middleware` operator can be configured multiple times, and the execution or
 <BFFOperatorCode>
 
 ```typescript
-import { Api, Query, Middleware } from '@modern-js/plugin-bff/hono-server';
+import { Api, Query, Middleware } from '@modern-js/plugin-bff/server';
 import { z } from 'zod';
 
 const UserSchema = z.object({
@@ -376,7 +376,7 @@ The `Pipe` operator can be configured multiple times. The execution order of fun
 <BFFOperatorCode>
 
 ```typescript
-import { Api, Query, Pipe } from '@modern-js/plugin-bff/hono-server';
+import { Api, Query, Pipe } from '@modern-js/plugin-bff/server';
 import { z } from 'zod';
 
 const UserSchema = z.object({
@@ -408,7 +408,7 @@ Also,
 <BFFOperatorCode>
 
 ```typescript
-import { Api, Query, Pipe } from '@modern-js/plugin-bff/hono-server';
+import { Api, Query, Pipe } from '@modern-js/plugin-bff/server';
 import { z } from 'zod';
 
 const UserSchema = z.object({
@@ -443,7 +443,7 @@ If you need to do more custom operations on the response, you can pass a functio
 <BFFOperatorCode>
 
 ```typescript
-import { Api, Query, Pipe } from '@modern-js/plugin-bff/hono-server';
+import { Api, Query, Pipe } from '@modern-js/plugin-bff/server';
 import { z } from 'zod';
 
 const UserSchema = z.object({
@@ -487,7 +487,7 @@ You can specify the status code returned by the interface through the `HttpCode(
 <BFFOperatorCode>
 
 ```typescript
-import { Api, Query, Data, HttpCode } from '@modern-js/plugin-bff/hono-server';
+import { Api, Query, Data, HttpCode } from '@modern-js/plugin-bff/server';
 import { z } from 'zod';
 
 const UserSchema = z.object({
@@ -523,7 +523,7 @@ Supports setting response headers through the `SetHeaders(headers: Record<string
 <BFFOperatorCode>
 
 ```typescript
-import { Api, Get, SetHeaders } from '@modern-js/plugin-bff/hono-server';
+import { Api, Get, SetHeaders } from '@modern-js/plugin-bff/server';
 
 export default Api(
   Get('/hello'),
@@ -543,7 +543,7 @@ Supports redirecting the interface through `Redirect(url: string)`:
 <BFFOperatorCode>
 
 ```typescript
-import { Api, Get, Redirect } from '@modern-js/plugin-bff/hono-server';
+import { Api, Get, Redirect } from '@modern-js/plugin-bff/server';
 
 export default Api(
   Get('/hello'),
@@ -561,7 +561,7 @@ As mentioned above, through operators, you can get `query`, `data`, `params`, et
 <BFFOperatorCode>
 
 ```typescript title="api/lambda/user.ts"
-import { Api, Get, Query } from '@modern-js/plugin-bff/hono-server';
+import { Api, Get, Query } from '@modern-js/plugin-bff/server';
 import { useHonoContext } from '@modern-js/server-runtime';
 import { z } from 'zod';
 
@@ -610,7 +610,7 @@ In frontend development, some server interfaces (such as some configuration inte
 <BFFOperatorCode>
 
 ```typescript
-import { Api, SetHeaders } from '@modern-js/plugin-bff/hono-server';
+import { Api, SetHeaders } from '@modern-js/plugin-bff/server';
 
 export const get = Api(
   // Cache will only take effect when using integrated calls or fetch for requests

package/docs/en/guides/basic-features/render/ssr-cache.mdx

@@ -35,7 +35,7 @@ export interface CacheControl {
 }
 ```
 
-Here, `customKey` is the custom cache key. By default, Modern.js uses the request `pathname` as the cache key, but developers can define it when necessary.
+Here, `customKey` is the custom cache key. By default, the cache key is derived from the request's origin, normalized pathname (trailing slash removed), and query string. When `customKey` is set, it fully replaces the default key: the `customKey` callback receives the normalized pathname (not the `CacheOptionProvider`'s `req`) and is responsible for the whole partition (e.g. by tenant, host, or query) — it must not embed raw cookies or other credentials into the returned key.
 
 **Function Type**
 
@@ -106,6 +106,19 @@ export const cacheOption: CacheOption = {
 
 The above `/home` and `/about` are patterns, meaning `/home/abc` will also match. You can use regex in these patterns, such as `/home/.+`.
 
+### Cache Policy
+
+The following policy is enforced automatically and cannot be overridden by the returned `CacheControl`:
+
+- Only `GET` requests are cached.
+- A request carrying a `Cookie` or `Authorization` header skips the cache unless `customKey` is set, since a custom key is treated as an explicit partitioning contract.
+- A request with `Cache-Control: private`, `no-cache`, or `no-store` skips the cache.
+- A response is only stored when it is `200`, has no `private`/`no-cache`/`no-store` in `Cache-Control`, has no `Set-Cookie`, and has no nonempty `Vary` header; otherwise any existing cache entry for that key is deleted instead of being written.
+- If a `stale` revalidation produces a response that is no longer cacheable (for example, it became per-user), that already-served stale response is unaffected, but the cache entry is evicted so subsequent requests no longer hit it.
+- A `CacheOptionProvider` returning `false` still disables caching entirely for that request, independent of the policy above.
+
+Cache keys are namespaced (`__ssr__cache:v2:...`). Older un-namespaced entries — including ones already stored in a custom `Container` — are never read back; they simply age out under the container's own eviction/TTL. There is no global cache flush.
+
 ### Cache Container
 
 By default, the server uses memory for caching. Typically, services are deployed in a Serverless container, creating a new process for each access, making it impossible to use the previous cache.