@brust/core 2.0.0-alpha.1 → 2.0.0-alpha.3

package/src/build/cloudflare.ts

@@ -0,0 +1,310 @@
+// `brust build --target cloudflare` (M4-CF spec §4): after the normal build, writes `<out>/cf/`:
+//   worker/      the @brust/core-cf glue + wasm (verbatim)  +  <appModuleDir>/brust-app.js (ONE Bun bundle, R2)
+//   assets/      Static Assets tree + _headers (R7)         wrangler.jsonc  (user config merged with brust's keys, R5)
+//   .stage/      the generated entry + the smoke harness (kept for inspection)
+import { cpSync, existsSync, mkdirSync, readFileSync, realpathSync, writeFileSync } from 'node:fs'
+import { builtinModules } from 'node:module'
+import { dirname, join, relative } from 'node:path'
+import type { BunPlugin } from 'bun'
+import { BrustConfigError, type CorsConfig, loadCors } from '../config'
+import { layoutAssets } from './cf-assets'
+import { type CfConfigJson, cfEntrySource } from './cf-entry'
+import { type CoreCf, resolveCoreCf } from './cf-core'
+import { type CacheNeed, mergeWrangler, readUserWrangler, renderWrangler, type UserWrangler, verifyCacheBindings } from './cf-wrangler'
+import { type CloudflareBuildConfig, CF_MIN_COMPAT_DATE } from './config'
+import { PRODUCTION, type SourceOf, sourceDirPlugin } from './bundle'
+import type { Compiled } from './compile'
+import { BuildError } from './errors'
+import type { CacheRecord } from './manifest'
+import { BUILTINS as CACHE_BUILTINS } from '../cache-adapter/load'
+
+export interface CfFlags {
+  fromSource: boolean
+  env: Record<string, string | undefined>
+}
+
+export interface CfPrepared {
+  cfg: CloudflareBuildConfig
+  core: CoreCf
+  user: UserWrangler
+  coreVersion: string
+  pkgName: string | undefined
+  /** brust.toml `[cors]`, validated before any write */
+  cors: CorsConfig | undefined
+  warnings: string[]
+}
+
+const DEFAULT_CFG: CloudflareBuildConfig = { name: undefined, compatibilityDate: undefined, l1Capacity: 256, jobCacheCapacity: 512, stats: false, edgeCache: 'off', alias: {} }
+
+/** Everything that can fail on the app's own input or install, before a byte is written (index.ts rule). */
+export async function prepareCloudflare(appRoot: string, cfg: CloudflareBuildConfig | null, flags: CfFlags): Promise<CfPrepared> {
+  const core = resolveCoreCf({ appRoot, fromSource: flags.fromSource, env: flags.env })
+  const user = await readUserWrangler(appRoot)
+  const warnings = [...core.warnings]
+  try {
+    const toml = Bun.file(join(appRoot, 'brust.toml'))
+    if (await toml.exists()) {
+      const root = Bun.TOML.parse(await toml.text()) as Record<string, unknown>
+      for (const k of ['server', 'workers']) if (k in root) warnings.push(`[brust] brust.toml [${k}] is ignored on this target`)
+    }
+  } catch {
+    // loadBuildConfig already reported a malformed brust.toml
+  }
+  let pkgName: string | undefined
+  try {
+    pkgName = (JSON.parse(readFileSync(join(appRoot, 'package.json'), 'utf8')) as { name?: string }).name
+  } catch {
+    pkgName = undefined
+  }
+  const coreVersion = String((JSON.parse(readFileSync(join(import.meta.dir, '..', '..', 'package.json'), 'utf8')) as { version?: string }).version ?? '0.0.0')
+  let cors: CorsConfig | undefined
+  try {
+    cors = await loadCors(appRoot)
+  } catch (e) {
+    if (e instanceof BrustConfigError) throw new BuildError('config', e.message)
+    throw e
+  }
+  return { cfg: cfg ?? DEFAULT_CFG, core, user, coreVersion, pkgName, cors, warnings }
+}
+
+export interface CfBuildCtx {
+  appRoot: string
+  entry: string
+  /** the FINAL dist dir (`out` is a tmp sibling that is renamed to it): wrangler paths are relative to `<dist>/cf` */
+  dist: string
+  compiled: Map<string, Compiled>
+  manifest: { components: Record<string, { template: string }>; actions?: { prefix: string; maxBodyBytes: number; maxResponseBytes?: number; crossSite?: 'reject' | 'allow' } | null; cache?: CacheRecord }
+  sourceOf: SourceOf
+  actionsEntry: string | null
+  /** A custom cache adapter's source module (absolute). */
+  cacheModule?: string | null
+  /** `[cache] get_timeout_ms` as written (absent → the Workers default, 100). */
+  cacheGetTimeoutMs?: number
+  log: (s: string) => void
+}
+
+const CORE_SRC = join(import.meta.dir, '..')
+const BUILTINS = new Set(builtinModules.filter((m) => !m.startsWith('_')))
+
+/** Violations of the Workers host surface: `bun`/`bun:*` anywhere in the graph (R2 f). */
+function cfGuard(appRoot: string, violations: string[]): BunPlugin {
+  return {
+    name: 'brust-cf-guard',
+    setup(b) {
+      b.onResolve({ filter: /^bun(:.*)?$/ }, (a) => {
+        violations.push(`${relative(appRoot, a.importer) || a.importer} imports ${a.path}`)
+        return { path: a.path, external: true }
+      })
+      b.onResolve({ filter: /^[a-z_]+(\/[a-z_/]+)?$/ }, (a) => (BUILTINS.has(a.path) ? { path: `node:${a.path}`, external: true } : undefined))
+    },
+  }
+}
+
+/** `[cloudflare] alias` (spec R12): a module whose resolved path is a key is replaced by its value. */
+function cfAlias(alias: Record<string, string>, sourceOf: SourceOf): BunPlugin {
+  return {
+    name: 'brust-cf-alias',
+    setup(b) {
+      if (Object.keys(alias).length === 0) return
+      b.onResolve({ filter: /.*/ }, (a) => {
+        if (a.importer === '' || a.importer.includes('/node_modules/')) return undefined
+        let abs: string
+        try {
+          abs = Bun.resolveSync(a.path, dirname(sourceOf.get(a.importer) ?? a.importer))
+        } catch {
+          return undefined
+        }
+        const to = alias[abs]
+        return to === undefined ? undefined : { path: to }
+      })
+    },
+  }
+}
+
+/** The CF bundle's stand-in for the napi addon (`native.ts` `require('../native/index.js')`, R8): every call
+ * fails loudly, since a Worker has no addon. */
+function cfNativeStub(handlersPath: string): BunPlugin {
+  const names = ['startServer', 'registerWorker', 'untilReady', 'beginDrain', 'cacheInvalidate', 'cacheStats', 'localAddr', 'planJobs', 'takeFetchBody', 'putFetchReply', 'cacheReplay', 'cacheL2Count', 'cacheClear']
+  return {
+    name: 'brust-cf-native',
+    setup(b) {
+      b.onResolve({ filter: /^\.\.\/native\/index\.js$/ }, (a) => (/[\\/]src[\\/]native\.ts$/.test(a.importer) ? { path: 'brust-cf-native', namespace: 'brust-cf' } : undefined))
+      b.onLoad({ filter: /.*/, namespace: 'brust-cf' }, () => ({
+        loader: 'js',
+        // cacheInvalidate -> the `rt.invalidate` the glue installed at start (ruling 19753649); the rest has no Worker meaning.
+        contents: `import { installedRuntime } from ${JSON.stringify(handlersPath)}\nconst no = (n) => () => { throw new Error(n + ' is not available on Cloudflare Workers') }\nmodule.exports = {${names.map((n) => (n === 'cacheInvalidate' ? 'cacheInvalidate: (a) => installedRuntime().invalidate(a)' : `${n}: no(${JSON.stringify(n)})`)).join(', ')}}\n`,
+      }))
+    },
+  }
+}
+
+/** The @brust/core `workerStorePlugin` twin for a bundle that inlines `@brust/core` (not external). */
+function cfStorePlugin(appRoot: string): BunPlugin {
+  return {
+    name: 'brust-cf-store',
+    setup(b) {
+      // The core's own re-export files (`src/store/{index,react}.ts`) must keep their real target, else they loop.
+      b.onResolve({ filter: /^@brust\/runtime-dom\/store(\/react)?$/ }, (a) =>
+        a.importer.startsWith(CORE_SRC) ? undefined : { path: Bun.resolveSync(a.path.replace('@brust/runtime-dom', '@brust/core'), appRoot) },
+      )
+    },
+  }
+}
+
+/** The entry's cache wiring (R8 on Workers): the custom source module or the built-in spec; an `env:`
+ * option cannot be resolved inside a Worker (no process env at bundle time) and is refused. */
+function cfEntryCache(c: CacheRecord, customModule: string | null) {
+  const noEnv = (o: Record<string, unknown> | undefined) => {
+    for (const [k, v] of Object.entries(o ?? {}))
+      if (typeof v === 'string' && v.startsWith('env:')) throw new BuildError('cache', `cache option ${k}: "env:" values are not available on Cloudflare Workers (use a binding)`)
+  }
+  noEnv(c.options)
+  noEnv(c.broadcastOptions)
+  const module = c.adapter === 'custom' ? customModule : CACHE_BUILTINS[c.adapter]
+  if (!module) throw new BuildError('cache', `cache adapter "${c.adapter}" has no module to bundle`)
+  return { module, options: c.options, ...(c.broadcast ? { broadcast: CACHE_BUILTINS[c.broadcast]!, broadcastOptions: c.broadcastOptions ?? {} } : {}) }
+}
+
+/** R2/R10: which Cloudflare bindings the configured cache needs (`[cache.cloudflare]` keys land in the adapter's options), or null. */
+export function cacheNeeds(c: CacheRecord | undefined): CacheNeed | null {
+  if (!c) return null
+  const opt = (o: Record<string, unknown> | undefined, k: string) => (typeof o?.[k] === 'string' ? (o[k] as string) : undefined)
+  const all = [c.options, c.broadcastOptions]
+  const names = [c.adapter, c.broadcast]
+  const kv = names.includes('cloudflare-kv') ? (all.map((o) => opt(o, 'kv_binding')).find((b) => b) ?? 'BRUST_CACHE') : undefined
+  const explicitDo = all.map((o) => opt(o, 'do_binding')).find((b) => b)
+  const dobind = names.includes('cloudflare-do') || explicitDo !== undefined ? (explicitDo ?? 'BRUST_CACHE_DO') : undefined
+  return kv === undefined && dobind === undefined ? null : { ...(kv !== undefined ? { kv } : {}), ...(dobind !== undefined ? { do: dobind } : {}) }
+}
+
+function smokeFiles(app: string, cache = false): { preload: string; smoke: string } {
+  const preload = `// generated: stubs the Workers-only modules so brust-app.js can be imported under Bun
+import { plugin } from 'bun'
+plugin({
+  name: 'brust-cf-smoke',
+  setup(b) {
+    b.module('cloudflare:workers', () => ({ exports: { env: {}, waitUntil() {}, DurableObject: class {} }, loader: 'object' }))
+  },
+})
+`
+  const smoke = `// generated: build-time smoke check of the CF bundle (child process; mock leaks are process-wide)
+const m = await import(${JSON.stringify(app)})
+const bad = []
+for (const k of ['loader', 'jobs', 'action', 'install']) if (typeof m[k] !== 'function') bad.push(k + ' is not a function')
+if (typeof m.MANIFEST !== 'string' || JSON.parse(m.MANIFEST).version !== 1) bad.push('MANIFEST.version !== 1')
+if (typeof m.CONFIG !== 'string' || JSON.parse(m.CONFIG).abi !== 1) bad.push('CONFIG.abi !== 1')
+if (typeof m.TEMPLATES !== 'object' || m.TEMPLATES === null) bad.push('TEMPLATES is not an object')
+const r = await m.loader('{}')
+if (typeof r !== 'string' || !r.includes('error')) bad.push('loader({}) did not resolve an error string: ' + String(r))${cache ? `
+try {
+  const out = m.install({ invalidate: () => ({ l1Removed: 0, jobRemoved: 0 }), l2Count: () => true })
+  if (!out || !out.cache || typeof out.cache.origin !== 'string') bad.push('install() returned no cache bridge')
+} catch (e) { bad.push('cache adapter: ' + (e && e.message ? e.message : String(e))) }` : ''}
+if (bad.length) { console.error(bad.join('\\n')); process.exit(1) }
+`
+  return { preload, smoke }
+}
+
+export async function buildCloudflare(out: string, ctx: CfBuildCtx, p: CfPrepared): Promise<string[]> {
+  const cfDir = join(out, 'cf')
+  const stage = join(cfDir, '.stage')
+  const warnings = [...p.warnings]
+  // R10: a Cloudflare cache built-in needs the user's own bindings; verify (never add) before anything is bundled.
+  const need = cacheNeeds(ctx.manifest.cache)
+  if (need) {
+    const v = verifyCacheBindings(p.user.config, need)
+    if (!v.ok) throw new BuildError('cf-config', v.message)
+  }
+  const doClass = need?.do !== undefined
+  if (doClass && existsSync(join(p.core.workerDir, 'main.js'))) throw new BuildError('cf-config', `@brust/core-cf ships its own worker/main.js; brust cannot add the BrustCacheDO re-export (R1)`)
+  mkdirSync(stage, { recursive: true })
+  cpSync(p.core.workerDir, join(cfDir, 'worker'), { recursive: true })
+
+  const templates: Record<string, string> = {}
+  for (const [id, c] of Object.entries(ctx.manifest.components)) {
+    const comp = ctx.compiled.get(id)
+    if (comp) templates[c.template] = comp.jinja
+  }
+  const templatesPath = join(stage, 'templates.json')
+  writeFileSync(templatesPath, JSON.stringify(templates))
+
+  const cors = p.cors
+  const a = ctx.manifest.actions
+  const cache = ctx.manifest.cache ? { ...ctx.manifest.cache, getTimeoutMs: ctx.cacheGetTimeoutMs ?? 100 } : null
+  const entryCache = cache ? cfEntryCache(cache, ctx.cacheModule ?? null) : null
+  const config: CfConfigJson = {
+    abi: 1,
+    generator: `brust/${p.coreVersion}`,
+    l1Capacity: p.cfg.l1Capacity,
+    jobCacheCapacity: p.cfg.jobCacheCapacity,
+    stats: p.cfg.stats,
+    edgeCache: p.cfg.edgeCache,
+    ...(cors ? { cors } : {}),
+    ...(a ? { actions: { prefix: a.prefix, maxBodyBytes: a.maxBodyBytes, maxResponseBytes: a.maxResponseBytes ?? 8_388_608, crossSite: a.crossSite ?? 'reject' } } : {}),
+    ...(cache ? { cache: { adapter: cache.adapter, getTimeoutMs: cache.getTimeoutMs, maxBodyBytes: cache.maxBodyBytes, namespace: cache.namespace, buildId: cache.buildId, epochIntervalMs: cache.epochIntervalMs } } : {}),
+  }
+  const entryPath = join(stage, 'brust-app.entry.js')
+  const jobsEntry = join(out, '.stage', 'jobs.ts')
+  writeFileSync(
+    entryPath,
+    cfEntrySource({ entry: ctx.entry, jobsEntry, actionsEntry: a ? ctx.actionsEntry : null, prefix: a?.prefix ?? '', manifestPath: join(out, 'manifest.json'), templatesPath, config, cache: entryCache, doClass }),
+  )
+  // Bare imports of the generated files resolve from the app root (an --out-dir outside the app has no node_modules above it).
+  // (registered by absolute AND real path: the bundler reports the real one, e.g. /private/var on macOS)
+  for (const f of [entryPath, jobsEntry]) {
+    ctx.sourceOf.set(f, ctx.entry)
+    ctx.sourceOf.set(realpathSync(f), ctx.entry)
+  }
+
+  const glue = p.core.meta.glue
+  const appDir = join(cfDir, 'worker', p.core.meta.appModuleDir)
+  const glueRel = relative(appDir, join(cfDir, 'worker', glue)).split('\\').join('/')
+  const glueSpec = glueRel.startsWith('.') ? glueRel : `./${glueRel}`
+  const violations: string[] = []
+  const res = await Bun.build({
+    entrypoints: [entryPath],
+    target: 'browser',
+    format: 'esm',
+    conditions: ['workerd', 'worker', 'browser'],
+    define: PRODUCTION,
+    minify: false,
+    external: ['node:*', 'cloudflare:*', glueSpec],
+    plugins: [cfGuard(ctx.appRoot, violations), cfAlias(p.cfg.alias, ctx.sourceOf), cfNativeStub(Bun.resolveSync('@brust/core/server-handlers', ctx.appRoot)), cfStorePlugin(ctx.appRoot), sourceDirPlugin(ctx.sourceOf, ctx.appRoot, ['node:*', 'cloudflare:*'])],
+  })
+  if (violations.length > 0) throw new BuildError('cf-unsupported', `${[...new Set(violations)].join('\n')}\nthese modules do not exist on Cloudflare Workers; swap them with [cloudflare] alias`)
+  if (!res.success) throw new BuildError('bundle', `cloudflare: ${res.logs.map(String).join('\n')}`)
+  const js = res.outputs.filter((o) => o.kind === 'entry-point')
+  if (js.length !== 1) throw new BuildError('bundle', `cloudflare: expected one entry-point output, got ${js.length}`)
+  for (const o of res.outputs) if (o.kind !== 'entry-point') warnings.push(`[brust] cloudflare bundle: dropped non-JS output ${o.path}`)
+  const appFile = join(appDir, 'brust-app.js')
+  mkdirSync(appDir, { recursive: true })
+  writeFileSync(appFile, await js[0]!.text())
+
+  const assets = layoutAssets(out, cfDir, p.coreVersion)
+  warnings.push(...assets.warnings)
+  const compatibilityDate = p.cfg.compatibilityDate ?? p.core.meta.compatibilityDate
+  if (compatibilityDate < CF_MIN_COMPAT_DATE) throw new BuildError('config', `compatibility_date ${compatibilityDate} is older than ${CF_MIN_COMPAT_DATE}`)
+  if (doClass) {
+    // R1: the Durable Object class must be exported by the deployed main module; the glue already imports ./brust-app.js, so it is one module copy.
+    const appRel = relative(join(cfDir, 'worker'), appFile).split('\\').join('/')
+    writeFileSync(
+      join(cfDir, 'worker', 'main.js'),
+      `// generated by brust build --target cloudflare (do not edit)\nexport * from "./${p.core.meta.main}"\nexport { default } from "./${p.core.meta.main}"\nexport { BrustCacheDO } from "./${appRel}"\n`,
+    )
+  }
+  const merged = mergeWrangler(p.user, { appRoot: ctx.appRoot, cfDir: join(ctx.dist, 'cf'), name: p.cfg.name, pkgName: p.pkgName, compatibilityDate, main: doClass ? 'main.js' : p.core.meta.main, version: p.coreVersion })
+  warnings.push(...merged.warnings)
+  writeFileSync(join(cfDir, 'wrangler.jsonc'), renderWrangler(merged.config))
+
+  const { preload, smoke } = smokeFiles(appFile, cache !== null)
+  writeFileSync(join(stage, 'smoke-preload.ts'), preload)
+  writeFileSync(join(stage, 'smoke.ts'), smoke)
+  const r = Bun.spawnSync([process.execPath, '--preload', join(stage, 'smoke-preload.ts'), join(stage, 'smoke.ts')], {
+    cwd: ctx.appRoot,
+    env: { ...process.env, NODE_ENV: 'production' },
+    stdout: 'pipe',
+    stderr: 'pipe',
+  })
+  if (r.exitCode !== 0) throw new BuildError('cf-smoke', `${r.stderr.toString().trim() || r.stdout.toString().trim()}\n(open bindings lazily: module top level runs at build time with env = {})`)
+  return warnings
+}

package/src/build/config.ts

@@ -4,23 +4,232 @@
 // `server_only` is the app config `serverOnly` of the compiler spec (§8.2): the compiler refuses
 // such an import in client code, and every browser bundle refuses to include it.
 import { join } from 'node:path'
-import { DEFAULT_ACTION_PREFIX, DEFAULT_MAX_BODY_BYTES, prefixError } from '../actions/prefix'
+import { DEFAULT_ACTION_PREFIX, DEFAULT_MAX_BODY_BYTES, DEFAULT_MAX_RESPONSE_BYTES, MAX_ACTION_BYTES, prefixError } from '../actions/prefix'
+import { ADAPTER_NAMES, BUILTINS, installHint } from '../cache-adapter/load'
 import { BuildError } from './errors'
 
-// [actions] (opt-in, ruling R6): present table => actions on. Crosses napi as u32.
+// [actions] (opt-in, ruling R6): present table => actions on. Both byte caps cross napi as u32 (F82: 1..64 MiB / 256 KiB..64 MiB).
 //   [actions]
-//   entry = "actions.ts"   prefix = "/_brust/action"   max_body_bytes = 262144
-const MAX_U32 = 0xffff_ffff
+//   entry = "actions.ts"   prefix = "/_brust/action"   max_body_bytes = 1048576  max_response_bytes = 8388608   cross_site = "reject" | "allow" (F87)
+const MIN_RESPONSE_BYTES = 262_144
 
 export interface ActionsBuildConfig {
   entry: string
   prefix: string
   maxBodyBytes: number
+  maxResponseBytes: number
+  crossSite: 'reject' | 'allow'
+}
+
+// [cloudflare] (M4-CF; only read by `--target cloudflare`, validated always so errors surface early):
+//   name = "my-worker"  compatibility_date = "2026-10-01"  l1_capacity = 256  job_cache_capacity = 512  stats = false
+//   edge_cache = "off"  [cloudflare.alias]  "lib/db.ts" = "lib/db.cf.ts"   # app-root-relative module swaps (spec R12)
+const CF_KEYS = new Set(['name', 'compatibility_date', 'l1_capacity', 'job_cache_capacity', 'stats', 'edge_cache', 'alias'])
+export const CF_MIN_COMPAT_DATE = '2026-08-04'
+const U32_MAX = 4_294_967_295
+
+export interface CloudflareBuildConfig {
+  name: string | undefined
+  compatibilityDate: string | undefined
+  l1Capacity: number
+  jobCacheCapacity: number
+  stats: boolean
+  edgeCache: 'off'
+  /** absolute module path -> absolute replacement path */
+  alias: Record<string, string>
+}
+
+// [cache] (cache adapters, opt-in; spec §6): a shared second tier behind the in-process cache.
+//   adapter = "redis" | "dragonfly" | "cloudflare-kv" | "cloudflare-do" | "custom"   module = "lib/cache.ts" (custom)
+//   broadcast = "<built-in>"   namespace = "<package name>"   get_timeout_ms = 50 (native) / 100 (Workers)
+//   max_body_bytes = 1048576   epoch_interval_ms = 1000   [cache.redis] url = "env:REDIS_URL"   [cache.cloudflare]   [cache.options]
+const CACHE_KEYS = new Set(['adapter', 'broadcast', 'module', 'namespace', 'get_timeout_ms', 'max_body_bytes', 'epoch_interval_ms', 'redis', 'cloudflare', 'options'])
+export const MAX_L2_BODY_BYTES = 67_108_864
+
+export interface CacheBuildConfig {
+  adapter: (typeof ADAPTER_NAMES)[number]
+  /** `custom`: the module, app-root-relative as written. */
+  module: string | undefined
+  broadcast: string | undefined
+  /** The factory's options: `[cache.redis]` / `[cache.cloudflare]` for built-ins, `[cache.options]` for custom. */
+  options: Record<string, unknown>
+  broadcastOptions: Record<string, unknown> | undefined
+  namespace: string
+  /** Absent = the runtime default (native 50, Workers 100). */
+  getTimeoutMs: number | undefined
+  maxBodyBytes: number
+  epochIntervalMs: number
 }
 
 export interface BuildConfig {
   serverOnly: string[]
   actions: ActionsBuildConfig | null
+  cloudflare: CloudflareBuildConfig | null
+  cache: CacheBuildConfig | null
+}
+
+const isTable = (v: unknown): v is Record<string, unknown> => v !== null && typeof v === 'object' && !Array.isArray(v)
+
+function rangeInt(file: string, key: string, v: unknown, lo: number, hi: number, dflt: number): number {
+  if (v === undefined) return dflt
+  if (typeof v !== 'number' || !Number.isInteger(v) || v < lo || v > hi)
+    throw new BuildError('cache', `${file}: cache.${key} must be an integer in ${lo}..${hi} (got ${String(v)})`)
+  return v
+}
+
+/** `[cache.redis]`'s keys and ranges (cache-redis R10); `@brust/cache-redis` validates the same list at worker boot. */
+const REDIS_INT_KEYS: ReadonlyArray<readonly [string, number, number]> = [
+  ['connect_timeout_ms', 100, 60_000],
+  ['max_body_bytes', 1, MAX_L2_BODY_BYTES],
+  ['marker_ttl_ms', 60_000, 604_800_000],
+  ['unlink_batch', 1, 10_000],
+  ['reconnect_min_ms', 10, 60_000],
+  ['reconnect_max_ms', 10, 600_000],
+]
+const REDIS_TLS_KEYS: Record<string, string> = { reject_unauthorized: 'boolean', server_name: 'string', ca_file: 'string' }
+
+function checkRedisTable(file: string, r: Record<string, unknown>): void {
+  const known = new Set(['url', 'tls', ...REDIS_INT_KEYS.map(([k]) => k)])
+  for (const k of Object.keys(r)) if (!known.has(k)) throw new BuildError('cache', `${file}: cache.redis.${k} is not a known key`)
+  for (const [k, lo, hi] of REDIS_INT_KEYS) rangeInt(file, `redis.${k}`, r[k], lo, hi, lo)
+  if (typeof r.reconnect_min_ms === 'number' && typeof r.reconnect_max_ms === 'number' && r.reconnect_max_ms < r.reconnect_min_ms)
+    throw new BuildError('cache', `${file}: cache.redis.reconnect_max_ms must be >= cache.redis.reconnect_min_ms`)
+  const tls = r.tls
+  if (tls === undefined || typeof tls === 'boolean') return
+  if (!isTable(tls)) throw new BuildError('cache', `${file}: cache.redis.tls must be a boolean or a table`)
+  for (const [k, v] of Object.entries(tls)) {
+    const want = REDIS_TLS_KEYS[k]
+    if (!want) throw new BuildError('cache', `${file}: cache.redis.tls.${k} is not a known key`)
+    if (typeof v !== want || v === '') throw new BuildError('cache', `${file}: cache.redis.tls.${k} must be a ${want === 'string' ? 'non-empty string' : want}`)
+  }
+}
+
+/** The option table a built-in reads. */
+function builtinOptions(name: string, t: Record<string, unknown>): Record<string, unknown> {
+  const key = name === 'redis' || name === 'dragonfly' ? 'redis' : 'cloudflare'
+  return { ...((t[key] as Record<string, unknown> | undefined) ?? {}) }
+}
+
+async function packageName(appRoot: string): Promise<string | undefined> {
+  const f = Bun.file(join(appRoot, 'package.json'))
+  if (!(await f.exists())) return undefined
+  try {
+    const n = ((await f.json()) as { name?: unknown }).name
+    return typeof n === 'string' && n.trim() ? n.trim() : undefined
+  } catch {
+    return undefined
+  }
+}
+
+async function parseCache(file: string, appRoot: string, raw: unknown): Promise<CacheBuildConfig | null> {
+  if (raw === undefined) return null
+  if (!isTable(raw)) throw new BuildError('cache', `${file}: [cache] must be a table`)
+  const t = raw
+  for (const k of Object.keys(t)) if (!CACHE_KEYS.has(k)) throw new BuildError('cache', `${file}: cache.${k} is not a known key`)
+  for (const k of ['redis', 'cloudflare', 'options'] as const)
+    if (t[k] !== undefined && !isTable(t[k])) throw new BuildError('cache', `${file}: [cache.${k}] must be a table`)
+  const adapter = t.adapter
+  if (typeof adapter !== 'string' || !(ADAPTER_NAMES as readonly string[]).includes(adapter))
+    throw new BuildError('cache', `${file}: cache.adapter must be one of ${ADAPTER_NAMES.map((n) => `"${n}"`).join(', ')} (got ${JSON.stringify(adapter)})`)
+  const name = adapter as CacheBuildConfig['adapter']
+  let module: string | undefined
+  if (name === 'custom') {
+    if (typeof t.module !== 'string' || t.module.trim() === '') throw new BuildError('cache', `${file}: cache.module is required for adapter "custom"`)
+    module = t.module.trim()
+  } else if (t.module !== undefined) throw new BuildError('cache', `${file}: cache.module is only for adapter "custom"`)
+  let broadcast: string | undefined
+  if (t.broadcast !== undefined) {
+    if (typeof t.broadcast !== 'string' || !(t.broadcast in BUILTINS))
+      throw new BuildError('cache', `${file}: cache.broadcast must name a built-in adapter (${Object.keys(BUILTINS).map((n) => `"${n}"`).join(', ')})`)
+    broadcast = t.broadcast
+  }
+  // `env:` indirection only: a literal URL may carry a password, so the error never echoes the value.
+  const redis = t.redis as Record<string, unknown> | undefined
+  if (redis?.url !== undefined && (typeof redis.url !== 'string' || !/^env:[A-Za-z_][A-Za-z0-9_]*$/.test(redis.url)))
+    throw new BuildError('cache', `${file}: cache.redis.url must be "env:NAME" (a literal URL is refused: it may hold a password)`)
+  if (redis) checkRedisTable(file, redis)
+  for (const n of [name, broadcast]) {
+    if (n === undefined || n === 'custom') continue
+    try {
+      Bun.resolveSync(BUILTINS[n]!, appRoot)
+    } catch {
+      throw new BuildError('cache', `${file}: ${installHint(n)}`)
+    }
+  }
+  const options = name === 'custom' ? { ...((t.options as Record<string, unknown> | undefined) ?? {}) } : builtinOptions(name, t)
+  let namespace = (await packageName(appRoot)) ?? 'brust'
+  if (t.namespace !== undefined) {
+    if (typeof t.namespace !== 'string' || !/^[A-Za-z0-9@._/-]{1,64}$/.test(t.namespace))
+      throw new BuildError('cache', `${file}: cache.namespace must be 1..64 of [A-Za-z0-9@._/-]`)
+    namespace = t.namespace
+  }
+  return {
+    adapter: name,
+    module,
+    broadcast,
+    options,
+    broadcastOptions: broadcast ? builtinOptions(broadcast, t) : undefined,
+    namespace,
+    getTimeoutMs: t.get_timeout_ms === undefined ? undefined : rangeInt(file, 'get_timeout_ms', t.get_timeout_ms, 1, 1000, 50),
+    maxBodyBytes: rangeInt(file, 'max_body_bytes', t.max_body_bytes, 1, MAX_L2_BODY_BYTES, 1_048_576),
+    epochIntervalMs: rangeInt(file, 'epoch_interval_ms', t.epoch_interval_ms, 250, 60_000, 1000),
+  }
+}
+
+function cfCapacity(file: string, key: string, v: unknown, dflt: number): number {
+  if (v === undefined) return dflt
+  if (typeof v !== 'number' || !Number.isInteger(v) || v < 1 || v > U32_MAX)
+    throw new BuildError('config', `${file}: cloudflare.${key} must be an integer in 1..${U32_MAX} (got ${String(v)})`)
+  return v
+}
+
+function parseCloudflare(file: string, appRoot: string, raw: unknown): CloudflareBuildConfig | null {
+  if (raw === undefined) return null
+  if (raw === null || typeof raw !== 'object' || Array.isArray(raw)) throw new BuildError('config', `${file}: [cloudflare] must be a table`)
+  const t = raw as Record<string, unknown>
+  for (const k of Object.keys(t)) if (!CF_KEYS.has(k)) throw new BuildError('config', `${file}: cloudflare.${k} is not a known key`)
+  if (t.name !== undefined && (typeof t.name !== 'string' || t.name.trim() === ''))
+    throw new BuildError('config', `${file}: cloudflare.name must be a non-empty string`)
+  let compatibilityDate: string | undefined
+  if (t.compatibility_date !== undefined) {
+    const d = t.compatibility_date
+    if (typeof d !== 'string' || !/^\d{4}-\d{2}-\d{2}$/.test(d)) throw new BuildError('config', `${file}: cloudflare.compatibility_date must be YYYY-MM-DD`)
+    if (d < CF_MIN_COMPAT_DATE)
+      throw new BuildError('config', `${file}: cloudflare.compatibility_date must be >= ${CF_MIN_COMPAT_DATE} (nodejs_compat is default from then)`)
+    compatibilityDate = d
+  }
+  if (t.stats !== undefined && typeof t.stats !== 'boolean') throw new BuildError('config', `${file}: cloudflare.stats must be a boolean`)
+  if (t.edge_cache !== undefined) {
+    if (t.edge_cache === 'workers-cache') throw new BuildError('config', `${file}: cloudflare.edge_cache = "workers-cache" lands with M4-CF-7`)
+    if (t.edge_cache !== 'off') throw new BuildError('config', `${file}: cloudflare.edge_cache must be "off"`)
+  }
+  const alias: Record<string, string> = {}
+  if (t.alias !== undefined) {
+    if (t.alias === null || typeof t.alias !== 'object' || Array.isArray(t.alias))
+      throw new BuildError('config', `${file}: cloudflare.alias must be a table of module paths`)
+    for (const [from, to] of Object.entries(t.alias as Record<string, unknown>)) {
+      if (typeof to !== 'string' || to.trim() === '') throw new BuildError('config', `${file}: cloudflare.alias["${from}"] must be a non-empty string`)
+      alias[resolveAlias(file, appRoot, from)] = resolveAlias(file, appRoot, to)
+    }
+  }
+  return {
+    name: t.name === undefined ? undefined : (t.name as string).trim(),
+    compatibilityDate,
+    l1Capacity: cfCapacity(file, 'l1_capacity', t.l1_capacity, 256),
+    jobCacheCapacity: cfCapacity(file, 'job_cache_capacity', t.job_cache_capacity, 512),
+    stats: (t.stats as boolean | undefined) ?? false,
+    edgeCache: 'off',
+    alias,
+  }
+}
+
+function resolveAlias(file: string, appRoot: string, p: string): string {
+  const rel = p.trim().replace(/^\.\//, '')
+  try {
+    return Bun.resolveSync(`./${rel}`, appRoot)
+  } catch {
+    throw new BuildError('config', `${file}: cloudflare.alias: cannot resolve "${p}" from the app root`)
+  }
 }
 
 function parseActions(file: string, raw: unknown): ActionsBuildConfig | null {
@@ -41,11 +250,23 @@ function parseActions(file: string, raw: unknown): ActionsBuildConfig | null {
   let maxBodyBytes = DEFAULT_MAX_BODY_BYTES
   if (t.max_body_bytes !== undefined) {
     const n = t.max_body_bytes
-    if (typeof n !== 'number' || !Number.isInteger(n) || n < 1 || n > MAX_U32)
-      throw new BuildError('config', `${file}: actions.max_body_bytes must be an integer in 1..${MAX_U32} (got ${String(n)})`)
+    if (typeof n !== 'number' || !Number.isInteger(n) || n < 1 || n > MAX_ACTION_BYTES)
+      throw new BuildError('config', `${file}: actions.max_body_bytes must be an integer in 1..${MAX_ACTION_BYTES} (got ${String(n)})`)
     maxBodyBytes = n
   }
-  return { entry, prefix, maxBodyBytes }
+  let maxResponseBytes = DEFAULT_MAX_RESPONSE_BYTES
+  if (t.max_response_bytes !== undefined) {
+    const n = t.max_response_bytes
+    if (typeof n !== 'number' || !Number.isInteger(n) || n < MIN_RESPONSE_BYTES || n > MAX_ACTION_BYTES)
+      throw new BuildError('config', `${file}: actions.max_response_bytes must be an integer in ${MIN_RESPONSE_BYTES}..${MAX_ACTION_BYTES} (got ${String(n)})`)
+    maxResponseBytes = n
+  }
+  let crossSite: 'reject' | 'allow' = 'reject'
+  if (t.cross_site !== undefined) {
+    if (t.cross_site !== 'reject' && t.cross_site !== 'allow') throw new BuildError('config', `${file}: actions.cross_site must be "reject" or "allow"`)
+    crossSite = t.cross_site
+  }
+  return { entry, prefix, maxBodyBytes, maxResponseBytes, crossSite }
 }
 
 const DEFAULT_ENTRY = 'actions.ts'
@@ -53,7 +274,7 @@ const DEFAULT_ENTRY = 'actions.ts'
 export async function loadBuildConfig(appRoot: string): Promise<BuildConfig> {
   const file = join(appRoot, 'brust.toml')
   const f = Bun.file(file)
-  if (!(await f.exists())) return { serverOnly: [], actions: null }
+  if (!(await f.exists())) return { serverOnly: [], actions: null, cloudflare: null, cache: null }
   let parsed: unknown
   try {
     parsed = Bun.TOML.parse(await f.text())
@@ -62,12 +283,14 @@ export async function loadBuildConfig(appRoot: string): Promise<BuildConfig> {
   }
   const root = (parsed ?? {}) as Record<string, unknown>
   const actions = parseActions(file, root.actions)
+  const cloudflare = parseCloudflare(file, appRoot, root.cloudflare)
+  const cache = await parseCache(file, appRoot, root.cache)
   const build = root.build
-  if (build === undefined) return { serverOnly: [], actions }
+  if (build === undefined) return { serverOnly: [], actions, cloudflare, cache }
   if (build === null || typeof build !== 'object' || Array.isArray(build)) throw new BuildError('config', `${file}: [build] must be a table`)
   const so = (build as Record<string, unknown>).server_only
-  if (so === undefined) return { serverOnly: [], actions }
+  if (so === undefined) return { serverOnly: [], actions, cloudflare, cache }
   if (!Array.isArray(so) || so.some((p) => typeof p !== 'string' || p.trim() === ''))
     throw new BuildError('config', `${file}: build.server_only must be an array of non-empty strings`)
-  return { serverOnly: so.map((p: string) => p.trim().replace(/^\.\//, '')), actions }
+  return { serverOnly: so.map((p: string) => p.trim().replace(/^\.\//, '')), actions, cloudflare, cache }
 }