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

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> {
@@ -175,13 +195,22 @@ async function buildInto(
   await buildJobs(out, compiled, ctx.sourceOf, appRoot, storeModules(manifest))
   manifest.actions =
     o.actions && o.actionsEntry
-      ? { entry: await buildActions(out, o.actionsEntry), prefix: o.actions.prefix, maxBodyBytes: o.actions.maxBodyBytes }
+      ? { 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

@@ -51,11 +51,13 @@ export interface RouteRecord {
   catch_all: boolean
 }
 
-/** `manifest.actions` (A3): `entry` is relative to dist; `maxBodyBytes` is camelCase by contract. */
+/** `manifest.actions` (A3): `entry` is relative to dist; `maxBodyBytes`/`maxResponseBytes` are camelCase by contract. */
 export interface ActionsRecord {
   entry: string
   prefix: string
   maxBodyBytes: number
+  maxResponseBytes: number
+  crossSite: 'reject' | 'allow'
 }
 
 export interface ManifestJson {
@@ -65,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) })
+  }
+}

package/src/cache-adapter/conformance.ts

@@ -0,0 +1,226 @@
+// `@brust/core/cache-adapter/conformance`: the cases every cache adapter must pass (spec §9),
+// registered with bun:test. Built-ins (lanes B/C) and custom adapters run the same suite:
+//
+//   import { runConformance } from '@brust/core/cache-adapter/conformance'
+//   runConformance(() => myAdapter(opts), { push: true, guard: true })
+//
+// Each case builds a fresh adapter with `make()` and closes it afterwards. Keys are unique per case.
+import { afterEach, describe, expect, test } from 'bun:test'
+import type { CacheAdapter, InvalidationEvent, SetMeta, StoredPage } from './types'
+
+export interface ConformanceCaps {
+  /** The broadcast is push (`subscribe`). */
+  push?: boolean
+  /** The broadcast is pull (`since`). */
+  pull?: boolean
+  /** The store refuses stale writes exactly (Redis Lua, DO, memory). */
+  guard?: boolean
+  /** The store invalidates (default true); `false` skips the tag/path invalidation cases (Cloudflare KV alone never invalidates). */
+  invalidate?: boolean
+}
+
+const enc = new TextEncoder()
+const page = (body: string | Uint8Array, headers: [string, string][] = [['content-type', 'text/html']]): StoredPage => ({
+  status: 200,
+  headers,
+  body: typeof body === 'string' ? enc.encode(body) : body,
+})
+const meta = (o: Partial<SetMeta> = {}): SetMeta => ({ ttlMs: 60_000, tags: [], method: 'GET', path: '/', stamp: null, ...o })
+
+async function until(what: string, f: () => boolean | Promise<boolean>, ms = 2000): Promise<void> {
+  const t0 = Date.now()
+  while (!(await f())) {
+    if (Date.now() - t0 > ms) throw new Error(`timed out: ${what}`)
+    await new Promise(r => setTimeout(r, 10))
+  }
+}
+
+export function runConformance(make: () => CacheAdapter | Promise<CacheAdapter>, caps: ConformanceCaps = {}): void {
+  let open: CacheAdapter[] = []
+  let n = 0
+  const key = () => `conf:${Date.now().toString(36)}:${n++}`
+  const fresh = async () => {
+    const a = await make()
+    await a.init?.({ namespace: 'conformance', buildId: 'b0', runtime: 'bun', workerId: 0 })
+    open.push(a)
+    return a
+  }
+  const store = async () => {
+    const a = await fresh()
+    if (!a.store) throw new Error(`adapter ${a.name} has no store`)
+    return { a, s: a.store }
+  }
+  afterEach(async () => {
+    const all = open
+    open = []
+    await Promise.allSettled(all.map(a => a.close?.()))
+  })
+
+  describe('cache adapter conformance', () => {
+    test('get of an absent key is a miss', async () => {
+      const { s } = await store()
+      const r = await s.get(key())
+      expect(r.page).toBeNull()
+      expect(r.entryStamp).toBeNull()
+    })
+
+    test('set then get round-trips status, headers (order + repeats) and body', async () => {
+      const { s } = await store()
+      const k = key()
+      const headers: [string, string][] = [
+        ['content-type', 'text/html; charset=utf-8'],
+        ['x-a', '1'],
+        ['x-a', '2'],
+        ['cache-control', 'no-store'],
+      ]
+      expect(await s.set(k, { status: 203, headers, body: enc.encode('<p>hi</p>') }, meta())).toBe(true)
+      const r = await s.get(k)
+      expect(r.page?.status).toBe(203)
+      expect(r.page?.headers).toEqual(headers)
+      expect(new TextDecoder().decode(r.page!.body)).toBe('<p>hi</p>')
+      expect(typeof r.storedAt === 'number' || r.storedAt === null).toBe(true)
+    })
+
+    test('bodies are binary-safe (all 256 byte values)', async () => {
+      const { s } = await store()
+      const k = key()
+      const body = Uint8Array.from({ length: 512 }, (_, i) => i % 256)
+      expect(await s.set(k, page(body), meta())).toBe(true)
+      expect(Array.from((await s.get(k)).page!.body)).toEqual(Array.from(body))
+    })
+
+    test('entryStamp round-trips the set stamp', async () => {
+      const { a, s } = await store()
+      const k = key()
+      const g = await s.get(k)
+      if (a.broadcast) expect(typeof g.stamp).toBe('number')
+      expect(await s.set(k, page('x'), meta({ stamp: g.stamp }))).toBe(true)
+      expect((await s.get(k)).entryStamp).toBe(g.stamp)
+    })
+
+    test('entries expire after ttlMs', async () => {
+      const { s } = await store()
+      const k = key()
+      expect(await s.set(k, page('x'), meta({ ttlMs: 1 }))).toBe(true)
+      await until('expiry', async () => (await s.get(k)).page === null)
+    })
+
+    if (caps.invalidate !== false) test('tag invalidation drops tagged pages and keeps unrelated ones', async () => {
+      const { s } = await store()
+      const [k1, k2, k3] = [key(), key(), key()]
+      await s.set(k1, page('1'), meta({ tags: ['items'], path: '/a' }))
+      await s.set(k2, page('2'), meta({ tags: ['other', 'items'], path: '/b' }))
+      await s.set(k3, page('3'), meta({ tags: ['other'], path: '/c' }))
+      await s.invalidate({ tags: ['items'] })
+      expect((await s.get(k1)).page).toBeNull()
+      expect((await s.get(k2)).page).toBeNull()
+      expect((await s.get(k3)).page).not.toBeNull()
+    })
+
+    if (caps.invalidate !== false) test('path + method invalidation drops that page only', async () => {
+      const { s } = await store()
+      const [k1, k2] = [key(), key()]
+      await s.set(k1, page('1'), meta({ path: '/x' }))
+      await s.set(k2, page('2'), meta({ path: '/y' }))
+      await s.invalidate({ path: '/x', method: 'POST' })
+      expect((await s.get(k1)).page).not.toBeNull()
+      await s.invalidate({ path: '/x' })
+      expect((await s.get(k1)).page).toBeNull()
+      expect((await s.get(k2)).page).not.toBeNull()
+    })
+
+    test('key invalidation is a store no-op', async () => {
+      const { s } = await store()
+      const k = key()
+      await s.set(k, page('1'), meta({ tags: ['t'] }))
+      await s.invalidate({ key: 'job-key' })
+      expect((await s.get(k)).page).not.toBeNull()
+    })
+
+    test('a body over maxBodyBytes is refused', async () => {
+      const { s } = await store()
+      const k = key()
+      expect(await s.set(k, page(new Uint8Array(s.maxBodyBytes + 1)), meta())).toBe(false)
+      expect((await s.get(k)).page).toBeNull()
+    })
+
+    if (caps.guard) {
+      test('a set whose stamp predates an invalidation of its tag is refused', async () => {
+        const { a, s } = await store()
+        const k = key()
+        const g = await s.get(k)
+        await s.invalidate({ tags: ['items'] })
+        await a.broadcast?.publish({ tags: ['items'] }, 'conf')
+        expect(await s.set(k, page('stale'), meta({ tags: ['items'], stamp: g.stamp }))).toBe(false)
+        expect((await s.get(k)).page).toBeNull()
+        const g2 = await s.get(k)
+        expect(await s.set(k, page('fresh'), meta({ tags: ['items'], stamp: g2.stamp }))).toBe(true)
+      })
+
+      test('L7b: a stale set racing invalidate (before its publish) never lands', async () => {
+        const { s } = await store()
+        const k = key()
+        const g = await s.get(k)
+        await s.invalidate({ tags: ['items'], path: '/p' })
+        expect(await s.set(k, page('stale'), meta({ tags: ['items'], stamp: g.stamp }))).toBe(false)
+        expect(await s.set(k, page('stale'), meta({ path: '/p', stamp: g.stamp }))).toBe(false)
+        expect((await s.get(k)).page).toBeNull()
+      })
+    }
+
+    test('publish seqs strictly increase; get().stamp is the last seq (one space)', async () => {
+      const a = await fresh()
+      if (!a.broadcast) return
+      const s1 = await a.broadcast.publish({ tags: ['a'] }, 'conf')
+      const s2 = await a.broadcast.publish({ path: '/b' }, 'conf')
+      expect(s2).toBeGreaterThan(s1)
+      if (a.store) expect((await a.store.get(key())).stamp).toBe(s2)
+    })
+
+    if (caps.push) {
+      test('push: in-order delivery with origin and args; unsubscribe stops it', async () => {
+        const a = await fresh()
+        const got: InvalidationEvent[] = []
+        const stop = await a.broadcast!.subscribe!(e => got.push(e), () => {})
+        const s1 = await a.broadcast!.publish({ tags: ['a'] }, 'o1')
+        const s2 = await a.broadcast!.publish({ path: '/b', method: 'GET' }, 'o2')
+        await until('delivery', () => got.length === 2)
+        expect(got).toEqual([
+          { seq: s1, origin: 'o1', args: { tags: ['a'] } },
+          { seq: s2, origin: 'o2', args: { path: '/b', method: 'GET' } },
+        ])
+        await stop()
+        await a.broadcast!.publish({ tags: ['c'] }, 'o1')
+        await new Promise(r => setTimeout(r, 50))
+        expect(got.length).toBe(2)
+      })
+    }
+
+    if (caps.pull) {
+      test('pull: since(0) after three publishes is contiguous', async () => {
+        const a = await fresh()
+        const b = a.broadcast!
+        const before = await b.since!(0)
+        const base = before.seq
+        for (const t of ['a', 'b', 'c']) await b.publish({ tags: [t] }, 'o')
+        const r = await b.since!(base)
+        expect(r.behind).toBe(false)
+        expect(r.seq).toBe(base + 3)
+        expect(r.events.map(e => e.seq)).toEqual([base + 1, base + 2, base + 3])
+        expect(r.events.map(e => e.args.tags?.[0])).toEqual(['a', 'b', 'c'])
+        expect(r.events[0]!.origin).toBe('o')
+        expect((await b.since!(r.seq)).events).toEqual([])
+        expect(typeof r.gen).toBe('string')
+      })
+
+      test('pull: a reader past the retained history is behind', async () => {
+        const a = await fresh()
+        const b = a.broadcast!
+        const base = (await b.since!(0)).seq
+        // 1025 events is beyond the spec's 1024-event ring.
+        for (let i = 0; i < 1025; i++) await b.publish({ tags: [`t${i}`] }, 'o')
+        expect((await b.since!(base)).behind).toBe(true)
+      })
+    }
+  })
+}

package/src/cache-adapter/index.ts

@@ -0,0 +1,10 @@
+// `@brust/core/cache-adapter`: the contract, the in-memory adapter and `defineCacheAdapter`.
+// No `bun`/`bun:*` import here (the Cloudflare bundle imports it); the conformance suite is its own
+// subpath, `@brust/core/cache-adapter/conformance`.
+import type { CacheAdapter, CacheAdapterFactory } from './types'
+
+export type * from './types'
+export { type MemoryAdapter, type MemoryAdapterOptions, type MemoryAdapterTest, memoryAdapter } from './memory'
+
+/** Identity, for type inference: `export default defineCacheAdapter((opts) => ({ … }))`. */
+export const defineCacheAdapter = <T extends CacheAdapter | CacheAdapterFactory>(a: T): T => a

package/src/cache-adapter/load.ts

@@ -0,0 +1,144 @@
+// Resolving and validating the configured adapter (cache-adapter R1, R8, R14). The build checks
+// that a built-in package is installed; this runs where the adapter lives (each Bun worker, or the
+// Workers isolate's `install`). No `bun` import: resolution is the caller's (`resolve`).
+import type { CacheAdapter, CacheAdapterFactory } from './types'
+
+/** What `brust build` writes to `manifest.cache` / `CONFIG.cache`. */
+export interface CacheManifest {
+  adapter: string
+  /** `custom`: the bundled module, relative to dist (native) — Workers import it in the entry. */
+  module?: string
+  /** A built-in broadcast composed onto the adapter (`broadcast = "cloudflare-do"`). */
+  broadcast?: string
+  options: Record<string, unknown>
+  /** Options of the composed broadcast's factory. */
+  broadcastOptions?: Record<string, unknown>
+  namespace: string
+  getTimeoutMs: number
+  maxBodyBytes: number
+  epochIntervalMs: number
+  buildId: string
+}
+
+/** The built-in adapters: each package subpath's default export is a factory (the lanes B/C contract). */
+export const BUILTINS: Readonly<Record<string, string>> = {
+  redis: '@brust/cache-redis',
+  dragonfly: '@brust/cache-redis/dragonfly',
+  'cloudflare-kv': '@brust/cache-cloudflare/kv',
+  'cloudflare-do': '@brust/cache-cloudflare/do',
+}
+
+export const ADAPTER_NAMES = ['redis', 'dragonfly', 'cloudflare-kv', 'cloudflare-do', 'custom'] as const
+
+/** A built-in name's install hint (the build's error). */
+export function installHint(name: string): string {
+  const spec = BUILTINS[name] ?? name
+  const pkg = spec.split('/').slice(0, 2).join('/')
+  return `adapter "${name}" needs ${pkg} (bun add ${pkg})`
+}
+
+/** `env:NAME` strings of a built-in's option table → `env[NAME]` (missing → a boot error naming NAME only). */
+export function resolveEnvOptions(o: Record<string, unknown>, env: Record<string, string | undefined>): Record<string, unknown> {
+  const out: Record<string, unknown> = {}
+  for (const [k, v] of Object.entries(o)) {
+    if (typeof v === 'string' && v.startsWith('env:')) {
+      const name = v.slice(4)
+      const val = env[name]
+      if (val === undefined || val === '') throw new Error(`cache adapter option ${k}: environment variable ${name} is not set`)
+      out[k] = val
+    } else out[k] = v
+  }
+  return out
+}
+
+/** A module's default export → the adapter (a factory is called with `options`). */
+export function instantiate(mod: unknown, options: Record<string, unknown>, what: string): CacheAdapter {
+  const d = (mod as { default?: unknown } | null)?.default ?? mod
+  const a = typeof d === 'function' ? (d as CacheAdapterFactory)(options) : d
+  return validateAdapter(a, what)
+}
+
+const fn = (o: unknown, k: string) => typeof (o as Record<string, unknown> | undefined)?.[k] === 'function'
+
+/** The shape check (TypeError naming what is wrong). */
+export function validateAdapter(a: unknown, what: string): CacheAdapter {
+  const bad = (m: string): never => {
+    throw new TypeError(`cache adapter ${what}: ${m}`)
+  }
+  if (!a || typeof a !== 'object') bad('the default export is not an adapter or a factory returning one')
+  const x = a as CacheAdapter
+  if (typeof x.name !== 'string' || !x.name) bad('no name')
+  if (!Array.isArray(x.runtimes) || x.runtimes.some(r => r !== 'bun' && r !== 'workers')) bad('runtimes must list "bun" and/or "workers"')
+  if (x.store && !(fn(x.store, 'get') && fn(x.store, 'set') && fn(x.store, 'invalidate') && typeof x.store.maxBodyBytes === 'number'))
+    bad('store needs get, set, invalidate and maxBodyBytes')
+  if (x.broadcast) {
+    if (!fn(x.broadcast, 'publish')) bad('broadcast needs publish')
+    const push = fn(x.broadcast, 'subscribe')
+    const pull = fn(x.broadcast, 'since')
+    if (push === pull) bad('broadcast needs exactly one of subscribe (push) or since (pull)')
+  }
+  if (!x.store && !x.broadcast) bad('neither a store nor a broadcast')
+  return x
+}
+
+/** R1 (native) / R14 (Workers): the runtime and the broadcast mode must fit where it runs. */
+export function checkRuntime(a: CacheAdapter, runtime: 'bun' | 'workers'): void {
+  if (!a.runtimes.includes(runtime))
+    throw new TypeError(`cache adapter "${a.name}" does not run on ${runtime === 'bun' ? 'Bun' : 'Cloudflare Workers'} (runtimes: ${a.runtimes.join(', ')})`)
+  if (!a.broadcast) return
+  const push = typeof a.broadcast.subscribe === 'function'
+  if (runtime === 'bun' && !push) throw new TypeError(`cache adapter "${a.name}": native needs a push broadcast (subscribe); pull (since) is Workers-only in v1`)
+  if (runtime === 'workers' && push) throw new TypeError(`cache adapter "${a.name}": push-only broadcast (subscribe) cannot run on Workers; it needs since (pull)`)
+}
+
+/**
+ * The configured adapter. `load(spec, builtin)` imports a module (the caller resolves it: a custom
+ * `module` relative to dist natively, a built-in package from the app root). `env` resolves
+ * built-in `env:` options.
+ */
+export async function loadAdapter(
+  m: CacheManifest,
+  runtime: 'bun' | 'workers',
+  load: (spec: string, builtin: boolean) => Promise<unknown>,
+  env: Record<string, string | undefined>,
+): Promise<CacheAdapter> {
+  let adapter: CacheAdapter
+  if (m.adapter === 'custom') {
+    if (!m.module) throw new Error('cache: adapter "custom" without a module')
+    adapter = instantiate(await load(m.module, false), m.options, `"custom" (${m.module})`)
+  } else {
+    const spec = BUILTINS[m.adapter]
+    if (!spec) throw new Error(`cache: unknown adapter "${m.adapter}"`)
+    adapter = instantiate(await load(spec, true), resolveEnvOptions(m.options, env), `"${m.adapter}"`)
+  }
+  if (m.broadcast) {
+    const spec = BUILTINS[m.broadcast]
+    if (!spec) throw new Error(`cache: unknown broadcast "${m.broadcast}"`)
+    const other = instantiate(await load(spec, true), resolveEnvOptions(m.broadcastOptions ?? {}, env), `"${m.broadcast}" (broadcast)`)
+    if (!other.broadcast) throw new TypeError(`cache adapter "${m.broadcast}" has no broadcast to compose`)
+    adapter = compose(adapter, other)
+  }
+  checkRuntime(adapter, runtime)
+  return adapter
+}
+
+/** `base`'s store with `other`'s broadcast; both are initialised and closed. Built explicitly (not a
+ * spread) so a class-based adapter keeps its prototype methods. */
+export function compose(base: CacheAdapter, other: CacheAdapter): CacheAdapter {
+  // A broadcast that knows its store partner (the Cloudflare DO + KV floors) composes itself.
+  const own = (other as { composeWith?: (store: CacheAdapter) => CacheAdapter }).composeWith
+  if (typeof own === 'function') return own.call(other, base)
+  return {
+    name: base.name,
+    runtimes: base.runtimes.filter(r => other.runtimes.includes(r)),
+    ...(base.store ? { store: base.store } : {}),
+    broadcast: other.broadcast,
+    async init(ctx) {
+      await base.init?.(ctx)
+      await other.init?.(ctx)
+    },
+    async close() {
+      await Promise.allSettled([base.close?.(), other.close?.()])
+    },
+  }
+}