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

package/src/build/config.ts

@@ -5,6 +5,7 @@
 // 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, 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. Both byte caps cross napi as u32 (F82: 1..64 MiB / 256 KiB..64 MiB).
@@ -20,9 +21,215 @@ export interface ActionsBuildConfig {
   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 {
@@ -67,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())
@@ -76,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 }
 }

package/src/build/index.ts

@@ -4,15 +4,16 @@
 // edited by hand. An out dir that could hold the app's own sources, or a non-empty one that is not
 // a previous brust dist (no `manifest.json` / `.brust` marker; `--force` overrides), is refused
 // before anything is written or removed.
-import { cpSync, existsSync, mkdirSync, readdirSync, realpathSync, renameSync, rmSync, statSync, writeFileSync } from 'node:fs'
+import { cpSync, existsSync, mkdirSync, readdirSync, readFileSync, realpathSync, renameSync, rmSync, statSync, writeFileSync } from 'node:fs'
 import { homedir } from 'node:os'
 import { basename, dirname, isAbsolute, join, parse, relative, resolve } from 'node:path'
 import { BrustRouteError, validateRoutes } from '../routes'
-import { type BrowserCtx, buildActions, buildClientChunks, buildJobs, buildReactChunks, buildRuntime, storeModules } from './bundle'
+import { type BrowserCtx, buildActions, buildCacheAdapter, buildClientChunks, buildJobs, buildReactChunks, buildRuntime, storeModules } from './bundle'
+import { type CfPrepared, buildCloudflare, prepareCloudflare } from './cloudflare'
 import { compileApp } from './compile'
-import { type ActionsBuildConfig, loadBuildConfig } from './config'
+import { type ActionsBuildConfig, type CacheBuildConfig, loadBuildConfig } from './config'
 import { BuildError } from './errors'
-import { writeManifest } from './manifest'
+import { type CacheRecord, type ManifestJson, writeManifest } from './manifest'
 import { scanRoutes } from './scan'
 
 export { BuildError } from './errors'
@@ -79,6 +80,10 @@ export async function runBuild(opts: {
   outDir: string
   /** Replace a non-empty out dir even without a previous build's marker. */
   force?: boolean
+  /** `cloudflare` also writes `<out>/cf/` (M4-CF); default `bun` = the unchanged build. */
+  target?: 'bun' | 'cloudflare'
+  /** `--wasm-from-source` (cloudflare only). */
+  wasmFromSource?: boolean
   log: (s: string) => void
 }): Promise<void> {
   const appRoot = resolve(opts.appRoot)
@@ -86,7 +91,7 @@ export async function runBuild(opts: {
   const dist = resolve(appRoot, opts.outDir)
   assertSafeOutDir(dist, appRoot, [entry, join(appRoot, 'public')])
   assertReplaceable(dist, opts.force)
-  const { serverOnly, actions } = await loadBuildConfig(appRoot)
+  const { serverOnly, actions, cloudflare, cache } = await loadBuildConfig(appRoot)
 
   // Everything that can fail on the app's own input runs before a byte is written.
   const { routes, componentFile } = await scanRoutes(entry)
@@ -114,7 +119,18 @@ export async function runBuild(opts: {
       }
     }
   }
-  assertSafeOutDir(dist, appRoot, [...componentFile.values(), ...(actionsEntry ? [actionsEntry] : [])])
+  let cacheModule: string | null = null
+  if (cache?.module !== undefined) {
+    cacheModule = resolve(appRoot, cache.module)
+    const rel = relative(appRoot, cacheModule)
+    if (isAbsolute(cache.module) || rel === '..' || rel.startsWith('../') || isAbsolute(rel) || !statOk(cacheModule)) {
+      throw new BuildError('cache', `cache.module ${cache.module} is not a file inside the app`)
+    }
+  }
+  assertSafeOutDir(dist, appRoot, [...componentFile.values(), ...(actionsEntry ? [actionsEntry] : []), ...(cacheModule ? [cacheModule] : [])])
+
+  // Config, @brust/core-cf resolution and the user's wrangler file fail here, before any write.
+  const cf = opts.target === 'cloudflare' ? await prepareCloudflare(appRoot, cloudflare, { fromSource: opts.wasmFromSource === true, env: process.env }) : null
 
   // Sibling of `dist` (same filesystem: the final rename is atomic), fixed name (no random bytes in
   // anything the bundler sees).
@@ -122,7 +138,7 @@ export async function runBuild(opts: {
   rmSync(tmp, { recursive: true, force: true })
   mkdirSync(tmp, { recursive: true })
   try {
-    await buildInto(tmp, { appRoot, entry, dist, leaves, componentFile, serverOnly, actions, actionsEntry, log: opts.log })
+    await buildInto(tmp, { appRoot, entry, dist, leaves, componentFile, serverOnly, actions, actionsEntry, cache, cacheModule, cf, log: opts.log })
     rmSync(join(tmp, '.stage'), { recursive: true, force: true })
     if (existsSync(dist)) {
       const old = join(dirname(dist), `.${basename(dist)}.brust-old`)
@@ -150,6 +166,10 @@ async function buildInto(
     actions: ActionsBuildConfig | null
     /** Absolute path of the actions entry (null when `[actions]` is off). */
     actionsEntry: string | null
+    cache: CacheBuildConfig | null
+    /** Absolute path of a custom cache adapter module. */
+    cacheModule: string | null
+    cf: CfPrepared | null
     log: (s: string) => void
   },
 ): Promise<void> {
@@ -177,11 +197,20 @@ async function buildInto(
     o.actions && o.actionsEntry
       ? { entry: await buildActions(out, o.actionsEntry), prefix: o.actions.prefix, maxBodyBytes: o.actions.maxBodyBytes, maxResponseBytes: o.actions.maxResponseBytes, crossSite: o.actions.crossSite }
       : null
+  if (o.cache) manifest.cache = await cacheRecord(out, manifest, o.cache, o.cacheModule)
   writeFileSync(join(out, 'manifest.json'), `${JSON.stringify(manifest, null, 2)}\n`)
   writeFileSync(join(out, MARKER), 'generated by `brust build`: this directory is replaced on every build\n')
 
   const pub = join(appRoot, 'public')
   if (existsSync(pub)) cpSync(pub, join(out, 'public'), { recursive: true })
+  if (o.cf) {
+    const warnings = await buildCloudflare(
+      out,
+      { appRoot, entry, dist: o.dist, compiled, manifest, sourceOf: ctx.sourceOf, actionsEntry: o.actionsEntry, cacheModule: o.cacheModule, cacheGetTimeoutMs: o.cache?.getTimeoutMs, log: o.log },
+      o.cf,
+    )
+    for (const w of warnings) o.log(w)
+  }
   const entryRel = relative(o.dist, entry)
   writeFileSync(
     join(out, 'index.js'),
@@ -197,3 +226,42 @@ async function buildInto(
     ].join('\n'),
   )
 }
+
+/** `manifest.cache` (R7, R8): the custom module bundled for the worker, the native defaults, and the
+ * build id every L2 key carries. */
+async function cacheRecord(out: string, manifest: ManifestJson, c: CacheBuildConfig, moduleAbs: string | null): Promise<CacheRecord> {
+  const module = moduleAbs ? await buildCacheAdapter(out, moduleAbs) : undefined
+  return {
+    adapter: c.adapter,
+    ...(module ? { module } : {}),
+    ...(c.broadcast ? { broadcast: c.broadcast, broadcastOptions: c.broadcastOptions ?? {} } : {}),
+    options: c.options,
+    namespace: c.namespace,
+    getTimeoutMs: c.getTimeoutMs ?? 50,
+    maxBodyBytes: c.maxBodyBytes,
+    epochIntervalMs: c.epochIntervalMs,
+    buildId: computeBuildId(out, manifest),
+  }
+}
+
+/** R7: the first 16 hex chars of sha256 over the manifest (without `cache`), every `jinja/*.jinja`
+ * (by name), `jobs.js` and `actions.js` when present: a rebuild of the same app keeps it, any change
+ * to what renders a page moves it (a deploy never serves an older build's L2 bodies). */
+export function computeBuildId(out: string, manifest: ManifestJson): string {
+  const h = new Bun.CryptoHasher('sha256')
+  const { cache: _, ...rest } = manifest
+  h.update(JSON.stringify(rest))
+  const jinja = join(out, 'jinja')
+  for (const f of (existsSync(jinja) ? readdirSync(jinja) : []).filter((f) => f.endsWith('.jinja')).sort()) {
+    h.update(`\0${f}\0`)
+    h.update(readFileSync(join(jinja, f)))
+  }
+  for (const f of ['jobs.js', 'actions.js']) {
+    const p = join(out, f)
+    if (existsSync(p)) {
+      h.update(`\0${f}\0`)
+      h.update(readFileSync(p))
+    }
+  }
+  return h.digest('hex').slice(0, 16)
+}

package/src/build/manifest.ts

@@ -67,6 +67,24 @@ export interface ManifestJson {
   assets: { runtime: string }
   jobs_module: string
   actions: ActionsRecord | null
+  /** `[cache]` (cache adapters); absent without one (the manifest is then byte-identical). */
+  cache?: CacheRecord
+}
+
+/** `manifest.cache` / `CONFIG.cache`: the adapter the runtime loads (`cache-adapter/load.ts`). */
+export interface CacheRecord {
+  adapter: string
+  /** `custom`: the bundled module, relative to dist. */
+  module?: string
+  broadcast?: string
+  options: Record<string, unknown>
+  broadcastOptions?: Record<string, unknown>
+  namespace: string
+  getTimeoutMs: number
+  maxBodyBytes: number
+  epochIntervalMs: number
+  /** 16 hex chars of sha256 over the build output (R7): every L2 key carries it. */
+  buildId: string
 }
 
 // biome-ignore lint/suspicious/noExplicitAny: IR JSON (externally tagged enums)

package/src/cache-adapter/bridge.ts

@@ -0,0 +1,91 @@
+// The worker side of the native `cache` call kind (cache-adapter R2/R3): Rust asks this worker's
+// adapter store to `get` or `set` one page. Every outcome is an A2 frame `[u32 LE meta_len][meta
+// JSON][body]` in the slot; a hit too large for the slot leaves by `putFetchReply` (meta `heap`), a
+// set body arrives by `takeFetchBody`. Never rejects (Rust's own timer bounds the get; the races
+// here guarantee the call settles, so a hung adapter never pins the slot).
+import type { HeapIo } from '../actions-bridge'
+import type { CacheStore, SetMeta, StoredPage } from './types'
+
+export interface CacheBridgeDeps {
+  store: CacheStore | undefined
+  getTimeoutMs: number
+  maxBodyBytes: number
+  count: (name: string) => void
+}
+
+/** A get is answered `{error}` this long after Rust's `get_timeout` gave up on it (the two timers must not race). */
+export const GET_SETTLE_SLACK_MS = 100
+
+/** A set gets this long before it is answered `{error}` (the slot is then released). */
+export const SET_TIMEOUT_MS = 5000
+
+type GetReq = { op: 'get'; key: string }
+type SetReq = { op: 'set'; key: string; status: number; headers: [string, string][]; meta: SetMeta; heap: number }
+
+const enc = new TextEncoder()
+const EMPTY = new Uint8Array(0)
+
+function frame(view: Uint8Array, slot: number, slots: number, meta: object, body: Uint8Array = EMPTY): number {
+  const sub = Math.floor(view.byteLength / Math.max(1, slots))
+  const dst = view.subarray(slot * sub, slot * sub + sub)
+  let m = enc.encode(JSON.stringify(meta))
+  if (4 + m.length + body.length > sub) {
+    m = enc.encode(JSON.stringify({ error: 'cache reply does not fit the slot' }))
+    body = EMPTY
+  }
+  new DataView(dst.buffer, dst.byteOffset, 4).setUint32(0, m.length, true)
+  dst.set(m, 4)
+  dst.set(body, 4 + m.length)
+  return 4 + m.length + body.length
+}
+
+const TIMEOUT = Symbol('timeout')
+function within<T>(p: Promise<T>, ms: number): Promise<T | typeof TIMEOUT> {
+  let t: ReturnType<typeof setTimeout> | undefined
+  return Promise.race([p, new Promise<typeof TIMEOUT>(r => (t = setTimeout(() => r(TIMEOUT), ms)))]).finally(() => clearTimeout(t))
+}
+
+const describe = (e: unknown) => (e instanceof Error ? e.message : String(e))
+
+export async function runCache(requestJson: string, view: Uint8Array, slot: number, slots: number, io: HeapIo, deps: CacheBridgeDeps): Promise<number> {
+  const out = (meta: object, body?: Uint8Array) => frame(view, slot, slots, meta, body)
+  try {
+    const store = deps.store
+    if (!store) return out({ error: 'no cache adapter store in this worker' })
+    const req = JSON.parse(requestJson) as GetReq | SetReq
+    if (req.op === 'get') {
+      const pending = store.get(req.key)
+      pending.catch(() => {})
+      // Rust's own `get_timeout` answers the request (as a timeout); this later race only frees the slot.
+      const r = await within(pending, deps.getTimeoutMs + GET_SETTLE_SLACK_MS)
+      if (r === TIMEOUT) return out({ error: 'get timed out' })
+      if (!r.page) return out({ hit: false, stamp: r.stamp })
+      const p = r.page
+      if (p.body.length > deps.maxBodyBytes) {
+        deps.count('errors')
+        return out({ hit: false, stamp: r.stamp })
+      }
+      const meta = { hit: true, status: p.status, headers: p.headers, stamp: r.stamp, entryStamp: r.entryStamp, storedAt: r.storedAt }
+      const sub = Math.floor(view.byteLength / Math.max(1, slots))
+      if (4 + enc.encode(JSON.stringify(meta)).length + p.body.length <= sub) return out(meta, p.body)
+      if (!io.putReply(slot, p.body)) {
+        deps.count('errors')
+        return out({ hit: false, stamp: r.stamp })
+      }
+      return out({ ...meta, heap: p.body.length })
+    }
+    if (req.op === 'set') {
+      const body = io.takeBody(slot)
+      if (!body || body.length !== req.heap) return out({ error: `set body ${body ? `${body.length} != ${req.heap}` : 'missing'} bytes` })
+      const page: StoredPage = { status: req.status, headers: req.headers, body }
+      const pending = store.set(req.key, page, req.meta)
+      pending.catch(() => {})
+      const ok = await within(pending, SET_TIMEOUT_MS)
+      if (ok === TIMEOUT) return out({ error: 'set timed out' })
+      return out({ ok: ok === true })
+    }
+    return out({ error: `unknown cache op ${(req as { op?: unknown }).op}` })
+  } catch (e) {
+    return out({ error: describe(e) })
+  }
+}