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

package/src/handlers.ts

@@ -0,0 +1,243 @@
+// The host-agnostic half of the worker (M4-CF lane 4): wire shapes + `makeHandlers`. No Bun, no
+// napi, no `node:*` — the Cloudflare entry imports it through `@brust/core/server-handlers`.
+// `worker.ts` re-exports everything here, so existing importers are unchanged.
+import { installServerResolver, type StoreSnapshot } from './store/core-adapter'
+import { collectSnapshot, getServerInstance, runInStoreContext, touchStores } from './store/server-context'
+import { type FlatRoute, isHttpErrorTrigger, isVerdict, type LoaderReq, type Route, type Verdict } from './routes'
+
+installServerResolver(getServerInstance)
+
+
+// ---- wire shapes (protocol.rs, camelCase) ----
+
+export interface LoaderRequest {
+  routeId: string
+  params: Record<string, string>
+  path: string
+  req: LoaderReq
+  /** M3-P P6: the chain has jobs — plan them in this call (`planJobs`). Optional to honour. */
+  plan?: boolean
+}
+
+export type LoaderResponse =
+  | { ok: true; data: Record<string, unknown>; headers?: Record<string, string>; store?: StoreSnapshot | null }
+  | { verdict: 'notFound'; data: unknown; store?: StoreSnapshot | null }
+  | { verdict: 'redirect'; location: string; status: number }
+  | { verdict: 'httpError'; status: number; body: string }
+  | { error: string }
+
+export type JobKind = 'precompute' | 'ssr'
+
+export interface JobCall {
+  /** Opaque, echoed back: `<componentId>/<jobId>[/<row>]` for a chain job,
+   * `<parentId>/<childId>_<k>/<jobId>[/<row>]` for an inlined child instance (pipeline.rs `plan_one`). */
+  id: string
+  componentId: string
+  kind: JobKind
+  // biome-ignore lint/suspicious/noExplicitAny: job inputs are arbitrary JSON
+  inputs: any
+  /** ssr: the react component to render (D6). */
+  target?: string
+  row?: number
+}
+
+export interface JobsRequest {
+  jobs: JobCall[]
+}
+
+export type JobResult = { id: string; value: unknown } | { id: string; error: string }
+
+export interface JobsResponse {
+  results: JobResult[]
+}
+
+/** The default export of `<dist>/<manifest.jobs_module>` (built by Task 6): component id → job fns. */
+// biome-ignore lint/suspicious/noExplicitAny: props are whatever the component takes
+export type JobsModule = Record<string, { precompute?: (props: any) => unknown; ssr?: (props: any) => string | Promise<string> }>
+
+/** The slice of `manifest.json` the worker reads: ssr job `literals` (S6 amendment). */
+export interface ManifestLike {
+  routes?: { id: string; chain: string[] }[]
+  components: Record<
+    string,
+    {
+      jobs: { id: string; kind?: string; target?: string; literals?: Record<string, unknown> }[]
+      children?: { id: string }[]
+      stores?: string[]
+    }
+  >
+  jobs_module?: string
+  /** `brust build` (M3-F A3): the actions entry, relative to dist. Absent/null = no actions. */
+  actions?: { entry: string; prefix: string; maxBodyBytes: number; maxResponseBytes?: number } | null
+}
+
+export function toJson(out: unknown): string {
+  try {
+    return JSON.stringify(out)
+  } catch (e) {
+    return JSON.stringify({ error: `response not serialisable: ${String(e)}` })
+  }
+}
+
+// ---- literals (S6 amendment: the worker merges an ssr job's `literals` over `call.inputs`) ----
+
+/** `"<componentId>/<jobId>"` → that job record's `literals` (only records that carry some). */
+export function literalsIndex(manifest: ManifestLike | undefined): Map<string, Record<string, unknown>> {
+  const out = new Map<string, Record<string, unknown>>()
+  for (const [cid, c] of Object.entries(manifest?.components ?? {}))
+    for (const j of c.jobs ?? []) if (j.literals && Object.keys(j.literals).length > 0) out.set(`${cid}/${j.id}`, j.literals)
+  return out
+}
+
+/** The manifest job id of a call: the segment after `componentId` in a chain id
+ * (`<cid>/<jobId>[/<row>]`), else the third segment of a child-instance id
+ * (`<parentId>/<cid>_<k>/<jobId>[/<row>]`). */
+export function jobIdOf(call: Pick<JobCall, 'id' | 'componentId'>): string | undefined {
+  const parts = call.id.split('/')
+  return parts[0] === call.componentId ? parts[1] : parts[2]
+}
+
+// ---- touched stores (M3-F D4) ----
+
+/** route id -> sorted unique union of `stores` over the route's chain, walking each component's
+ * `children[].id` and `jobs[].target` transitively. Routes with an empty union are absent. */
+export function routeStoresIndex(manifest: ManifestLike | undefined): Map<string, string[]> {
+  const out = new Map<string, string[]>()
+  const comps = manifest?.components ?? {}
+  for (const r of manifest?.routes ?? []) {
+    const acc = new Set<string>()
+    const seen = new Set<string>()
+    const walk = (id: string) => {
+      if (seen.has(id)) return
+      seen.add(id)
+      const c = comps[id]
+      if (!c) return
+      for (const p of c.stores ?? []) acc.add(p)
+      for (const k of c.children ?? []) walk(k.id)
+      for (const j of c.jobs ?? []) if (j.target) walk(j.target)
+    }
+    for (const id of r.chain ?? []) walk(id)
+    if (acc.size > 0) out.set(r.id, [...acc].sort())
+  }
+  return out
+}
+
+/** R1: `store` is assigned only when a store was touched; absent otherwise. */
+function withStore<T extends LoaderResponse>(r: T): T {
+  const s = collectSnapshot()
+  if (s) (r as { store?: StoreSnapshot | null }).store = s
+  return r
+}
+
+// ---- handlers ----
+
+/** `parent`: the data the chain merged before the verdict. A notFound renders the route's
+ * template (layouts included), so the layouts' data stays under the verdict's own keys. */
+function verdictJson(v: Verdict, parent: Record<string, unknown>): LoaderResponse {
+  if (v.status === 404) {
+    const own = v.data ?? {}
+    return { verdict: 'notFound', data: typeof own === 'object' && !Array.isArray(own) ? { ...parent, ...own } : own }
+  }
+  return { verdict: 'redirect', location: v.headers?.Location ?? '/', status: v.status }
+}
+
+export interface Handlers {
+  loader(req: LoaderRequest): Promise<LoaderResponse>
+  jobs(req: JobsRequest): Promise<JobsResponse>
+}
+
+/** `leaves` from `flattenRoutes` (ids must match the manifest's route ids); `jobs` the jobs
+ * module; `manifest` supplies ssr `literals` (omit → no merge). */
+export function makeHandlers(opts: {
+  leaves: FlatRoute[]
+  jobs: JobsModule
+  manifest?: ManifestLike
+  /** `jobs.js` `stores` table (R2): C3 path -> module namespace. */
+  stores?: Record<string, object>
+}): Handlers {
+  const byId = new Map(opts.leaves.map((l) => [l.id, l]))
+  const literals = literalsIndex(opts.manifest)
+  const jobs = opts.jobs
+  const storeIdx = routeStoresIndex(opts.manifest)
+  const storeTable = opts.stores ?? {}
+
+  async function runJob(call: JobCall): Promise<JobResult> {
+    const owner = call.kind === 'ssr' ? (call.target ?? call.componentId) : call.componentId // D6
+    const fn = jobs[owner]?.[call.kind]
+    if (typeof fn !== 'function') return { id: call.id, error: `no ${call.kind} job for component ${owner}` }
+    try {
+      let props = call.inputs
+      if (call.kind === 'ssr') {
+        const jid = jobIdOf(call)
+        const lit = jid === undefined ? undefined : literals.get(`${call.componentId}/${jid}`)
+        if (lit) props = { ...(props ?? {}), ...lit }
+        // Precompute runs outside any scope (D8); ssr runs in a scope seeded from `__store`, which props never see.
+        const seed = (props?.__store ?? null) as StoreSnapshot | null
+        if (props && '__store' in props) {
+          const { __store: _, ...rest } = props
+          props = rest
+        }
+        const p = props
+        return { id: call.id, value: await runInStoreContext(() => fn(p), seed) }
+      }
+      return { id: call.id, value: await fn(props) }
+    } catch (e) {
+      return { id: call.id, error: String(e) }
+    }
+  }
+
+  return {
+    // 0.1.x `runNativeChainLoaders`: root → leaf, flat merge (later keys win), first verdict stops
+    // (a notFound keeps what the chain merged so far: verdictJson).
+    async loader(req) {
+      const leaf = byId.get(req.routeId)
+      if (!leaf) return { error: `unknown routeId ${req.routeId}` }
+      // One object for the whole chain: each level's keys are assigned INTO it (later keys win,
+      // first-seen key order — what `{...merged, ...r}` produced) instead of re-spreading every
+      // key once per level (M3-P P1). `merged` is fresh per call; a loader's own object is never
+      // written to. Null prototype: with no `__proto__` setter to hit, an own "__proto__" key in a
+      // loader's data is assigned as data, as the spread copied it.
+      return runInStoreContext(async () => {
+        const merged: Record<string, unknown> = Object.create(null)
+        try {
+          const touch = storeIdx.get(req.routeId)
+          if (touch) touchStores(touch, storeTable)
+          for (const node of leaf.chain) {
+            if (!node.loader) continue
+            let r: unknown
+            try {
+              r = await node.loader({ params: req.params, path: req.path, req: req.req })
+            } catch (e) {
+              if (isHttpErrorTrigger(e)) return { verdict: 'httpError', status: e.status, body: e.body } as LoaderResponse
+              throw e
+            }
+            if (isVerdict(r)) {
+              const v = verdictJson(r, merged)
+              return 'verdict' in v && v.verdict === 'notFound' ? withStore(v) : v
+            }
+            if (r && typeof r === 'object') Object.assign(merged, r)
+          }
+          return withStore({ ok: true, data: merged } as LoaderResponse)
+        } catch (e) {
+          return { error: String(e) } as LoaderResponse
+        }
+      })
+    },
+    // One request carries every job of the page; a per-job failure keeps the other results.
+    async jobs(req) {
+      return { results: await Promise.all((req.jobs ?? []).map(runJob)) }
+    },
+  }
+}
+
+/** Wraps an async handler for a JSON-string boundary: parses, calls, serialises; NEVER rejects
+ * (a parse error or a throwing handler resolves `{"error":…}`, like `makeDispatch`). */
+export function jsonCall<Q, R>(fn: (q: Q) => Promise<R>): (json: string) => Promise<string> {
+  return async (json) => {
+    try {
+      return toJson(await fn(JSON.parse(json)))
+    } catch (e) {
+      return toJson({ error: String(e) })
+    }
+  }
+}

package/src/native.ts

@@ -31,6 +31,16 @@ export interface StartOptions {
   cors?: CorsOptions
   /** The actions subtree (M3-F A3); absent = no actions. Boot error `actions: …` when invalid. */
   actions?: ActionsOptions
+  /** The cache adapter (`manifest.cache`); absent = none (byte-identical server). */
+  l2?: L2Options
+}
+/** napi `NapiL2Options`; defaults 50 ms, 1048576 bytes. */
+export interface L2Options {
+  adapter: string
+  getTimeoutMs?: number
+  maxBodyBytes?: number
+  namespace: string
+  buildId: string
 }
 /** napi `NapiCorsOptions` (camelCase keys; snake_case keys are silently dropped). */
 export interface CorsOptions {
@@ -50,7 +60,7 @@ export interface ActionsOptions {
   /** F87: cross-site mutating requests. Default `reject`. */
   crossSite?: 'reject' | 'allow'
 }
-export type WorkerFn = (kind: 'loader' | 'jobs' | 'fetch', requestJson: string, slot: number) => Promise<number>
+export type WorkerFn = (kind: 'loader' | 'jobs' | 'fetch' | 'cache', requestJson: string, slot: number) => Promise<number>
 export interface NativeBinding {
   startServer(opts: StartOptions): void
   registerWorker(buf: Uint8Array, slots: number, f: WorkerFn): number
@@ -65,6 +75,12 @@ export interface NativeBinding {
   takeFetchBody(slot: number): Uint8Array | null
   /** F82 — hand Rust a response body too large for the slot; false = declined. Never throws. */
   putFetchReply(slot: number, body: Uint8Array): boolean
+  /** cache adapter R10 — a foreign broadcast event: tier 1 + the floor at `seq`; never re-published. */
+  cacheReplay(args: InvalidateArgs, seq: number | null): InvalidateResult
+  /** cache adapter R9 — bump `stats.l2[name]`; false = unknown name / no adapter / no server. Never throws. */
+  cacheL2Count(name: string): boolean
+  /** cache adapter R10 — drop both tier-1 caches (a broadcast gap); the L1 entries removed. */
+  cacheClear(): number
 }
 
 let binding: NativeBinding | null = null
@@ -93,3 +109,6 @@ export const localAddr = (): string => native().localAddr()
 export const planJobs = (slot: number, len: number): string => native().planJobs(slot, len)
 export const takeFetchBody = (slot: number): Uint8Array | null => native().takeFetchBody(slot)
 export const putFetchReply = (slot: number, body: Uint8Array): boolean => native().putFetchReply(slot, body)
+export const cacheReplay = (args: InvalidateArgs, seq: number | null): InvalidateResult => native().cacheReplay(args, seq)
+export const cacheL2Count = (name: string): boolean => native().cacheL2Count(name)
+export const cacheClear = (): number => native().cacheClear()

package/src/run.ts

@@ -23,9 +23,11 @@ export interface RunOptions {
 /** The manifest fields `run` needs (build/manifest.ts owns the full shape). */
 export interface RunManifest {
   actions?: { entry: string; prefix: string; maxBodyBytes: number; maxResponseBytes?: number; crossSite?: 'reject' | 'allow' } | null
+  /** `[cache]`: the server's L2 settings (the workers load the adapter itself). */
+  cache?: { adapter: string; getTimeoutMs: number; maxBodyBytes: number; namespace: string; buildId: string } | null
 }
 
-/** Pure: the napi `StartOptions`. No actions/cors → exactly the pre-actions keys. */
+/** Pure: the napi `StartOptions`. No actions/cors/cache → exactly the pre-actions keys. */
 export function startOptions(cfg: BrustConfig, distDir: string, m: RunManifest, version: string): StartOptions {
   return {
     host: cfg.host,
@@ -37,6 +39,7 @@ export function startOptions(cfg: BrustConfig, distDir: string, m: RunManifest,
     generator: `brust/${version}`,
     ...(m.actions ? { actions: { prefix: m.actions.prefix, maxBodyBytes: m.actions.maxBodyBytes, ...(m.actions.maxResponseBytes !== undefined ? { maxResponseBytes: m.actions.maxResponseBytes } : {}), ...(m.actions.crossSite ? { crossSite: m.actions.crossSite } : {}) } } : {}),
     ...(cfg.cors ? { cors: cfg.cors } : {}),
+    ...(m.cache ? { l2: { adapter: m.cache.adapter, getTimeoutMs: m.cache.getTimeoutMs, maxBodyBytes: m.cache.maxBodyBytes, namespace: m.cache.namespace, buildId: m.cache.buildId } } : {}),
   }
 }
 
@@ -86,6 +89,8 @@ export async function run(opts: RunOptions = {}): Promise<void> {
     BRUST_RENDER_SLOTS: String(cfg.renderSlots),
     BRUST_DIST_DIR: distDir,
     BRUST_APP_ENTRY: entry,
+    // One cache-adapter origin per process: its workers' published events are not replayed here.
+    BRUST_CACHE_ORIGIN: crypto.randomUUID(),
   }
 
   let ready = false

package/src/server-handlers.ts

@@ -0,0 +1,32 @@
+// What the generated Cloudflare entry (`brust-app.js`) imports: the host-agnostic handler code and the
+// store-scoped action fetch. No Bun / worker_threads here; `actions-bridge`'s napi import is stubbed by the
+// CF bundle (M4-CF R8).
+import { type CfCacheBridge, type CfInstallExt, installCache } from './cache-adapter/workers'
+import type { InvalidateArgs, InvalidateResult } from './native'
+
+export { fetchInScope, noActions } from './actions-bridge'
+export { jsonCall, makeHandlers } from './handlers'
+export { flattenRoutes } from './routes'
+
+/** What the wasm side hands over at start (`#[event(start]` -> `install({ invalidate, l2Count })`, ruling 19753649). */
+export interface CfRuntime {
+  invalidate(args: InvalidateArgs): InvalidateResult
+  /** Bumps a `stats.l2` counter (cache adapters R9). */
+  l2Count?(name: string): boolean
+}
+export type { CfCacheBridge, CfInstallExt }
+
+let rt: CfRuntime | null = null
+
+/** Called by the wasm glue once at Worker start; the CF bundle's napi stub forwards `cacheInvalidate` to it.
+ * With a cache adapter (`ext`, from the generated entry) it answers the adapter bridge (R11, R14). */
+export function install(runtime: CfRuntime, ext?: CfInstallExt): { cache: CfCacheBridge | null } {
+  rt = runtime
+  return { cache: ext ? installCache(runtime, ext) : null }
+}
+
+/** The installed runtime; throws before `install` (a request cannot arrive earlier). */
+export function installedRuntime(): CfRuntime {
+  if (!rt) throw new Error('brust: the Cloudflare runtime is not installed (install(rt) was not called at start)')
+  return rt
+}

package/src/worker.ts

@@ -1,79 +1,17 @@
 // The Bun side of contract 7 (`crates/brust-server/src/protocol.rs`): requests arrive as inline
 // JSON, responses go into this worker's SharedArrayBuffer slot (SAB rule, `dispatch.rs`). A
 // handler NEVER rejects across the tsfn: every failure becomes `{error}` / `{id, error}`.
-import { join, resolve } from 'node:path'
+import { dirname, join, resolve } from 'node:path'
 import { workerData } from 'node:worker_threads'
-import { runFetch, setActionsApp, setActionsLimits } from './actions-bridge'
+import { type HeapIo, runFetch, setActionsApp, setActionsLimits } from './actions-bridge'
 import { DEFAULT_MAX_RESPONSE_BYTES } from './actions/prefix'
-import { planJobs, registerWorker } from './native'
-import { installServerResolver, type StoreSnapshot } from './store/core-adapter'
-import { collectSnapshot, getServerInstance, runInStoreContext, touchStores } from './store/server-context'
-import { type FlatRoute, flattenRoutes, isHttpErrorTrigger, isVerdict, type LoaderReq, type Route, type Verdict } from './routes'
+import { type CacheBridgeDeps, runCache } from './cache-adapter/bridge'
+import type { CacheManifest } from './cache-adapter/load'
+import { type Handlers, type JobsModule, type ManifestLike, makeHandlers, toJson } from './handlers'
+import { cacheClear, cacheL2Count, cacheReplay, planJobs, putFetchReply, registerWorker, takeFetchBody } from './native'
+import { flattenRoutes, type Route } from './routes'
 
-installServerResolver(getServerInstance)
-
-// ---- wire shapes (protocol.rs, camelCase) ----
-
-export interface LoaderRequest {
-  routeId: string
-  params: Record<string, string>
-  path: string
-  req: LoaderReq
-  /** M3-P P6: the chain has jobs — plan them in this call (`planJobs`). Optional to honour. */
-  plan?: boolean
-}
-
-export type LoaderResponse =
-  | { ok: true; data: Record<string, unknown>; headers?: Record<string, string>; store?: StoreSnapshot | null }
-  | { verdict: 'notFound'; data: unknown; store?: StoreSnapshot | null }
-  | { verdict: 'redirect'; location: string; status: number }
-  | { verdict: 'httpError'; status: number; body: string }
-  | { error: string }
-
-export type JobKind = 'precompute' | 'ssr'
-
-export interface JobCall {
-  /** Opaque, echoed back: `<componentId>/<jobId>[/<row>]` for a chain job,
-   * `<parentId>/<childId>_<k>/<jobId>[/<row>]` for an inlined child instance (pipeline.rs `plan_one`). */
-  id: string
-  componentId: string
-  kind: JobKind
-  // biome-ignore lint/suspicious/noExplicitAny: job inputs are arbitrary JSON
-  inputs: any
-  /** ssr: the react component to render (D6). */
-  target?: string
-  row?: number
-}
-
-export interface JobsRequest {
-  jobs: JobCall[]
-}
-
-export type JobResult = { id: string; value: unknown } | { id: string; error: string }
-
-export interface JobsResponse {
-  results: JobResult[]
-}
-
-/** The default export of `<dist>/<manifest.jobs_module>` (built by Task 6): component id → job fns. */
-// biome-ignore lint/suspicious/noExplicitAny: props are whatever the component takes
-export type JobsModule = Record<string, { precompute?: (props: any) => unknown; ssr?: (props: any) => string | Promise<string> }>
-
-/** The slice of `manifest.json` the worker reads: ssr job `literals` (S6 amendment). */
-export interface ManifestLike {
-  routes?: { id: string; chain: string[] }[]
-  components: Record<
-    string,
-    {
-      jobs: { id: string; kind?: string; target?: string; literals?: Record<string, unknown> }[]
-      children?: { id: string }[]
-      stores?: string[]
-    }
-  >
-  jobs_module?: string
-  /** `brust build` (M3-F A3): the actions entry, relative to dist. Absent/null = no actions. */
-  actions?: { entry: string; prefix: string; maxBodyBytes: number; maxResponseBytes?: number } | null
-}
+export * from './handlers'
 
 // ---- SAB slot writer ----
 
@@ -103,165 +41,6 @@ export type PlanJobs = (slot: number, len: number) => string
 export const PLAN_DECLINED = '!'
 const PLANNED = { planned: true } as const
 
-function toJson(out: unknown): string {
-  try {
-    return JSON.stringify(out)
-  } catch (e) {
-    return JSON.stringify({ error: `response not serialisable: ${String(e)}` })
-  }
-}
-
-// ---- literals (S6 amendment: the worker merges an ssr job's `literals` over `call.inputs`) ----
-
-/** `"<componentId>/<jobId>"` → that job record's `literals` (only records that carry some). */
-export function literalsIndex(manifest: ManifestLike | undefined): Map<string, Record<string, unknown>> {
-  const out = new Map<string, Record<string, unknown>>()
-  for (const [cid, c] of Object.entries(manifest?.components ?? {}))
-    for (const j of c.jobs ?? []) if (j.literals && Object.keys(j.literals).length > 0) out.set(`${cid}/${j.id}`, j.literals)
-  return out
-}
-
-/** The manifest job id of a call: the segment after `componentId` in a chain id
- * (`<cid>/<jobId>[/<row>]`), else the third segment of a child-instance id
- * (`<parentId>/<cid>_<k>/<jobId>[/<row>]`). */
-export function jobIdOf(call: Pick<JobCall, 'id' | 'componentId'>): string | undefined {
-  const parts = call.id.split('/')
-  return parts[0] === call.componentId ? parts[1] : parts[2]
-}
-
-// ---- touched stores (M3-F D4) ----
-
-/** route id -> sorted unique union of `stores` over the route's chain, walking each component's
- * `children[].id` and `jobs[].target` transitively. Routes with an empty union are absent. */
-export function routeStoresIndex(manifest: ManifestLike | undefined): Map<string, string[]> {
-  const out = new Map<string, string[]>()
-  const comps = manifest?.components ?? {}
-  for (const r of manifest?.routes ?? []) {
-    const acc = new Set<string>()
-    const seen = new Set<string>()
-    const walk = (id: string) => {
-      if (seen.has(id)) return
-      seen.add(id)
-      const c = comps[id]
-      if (!c) return
-      for (const p of c.stores ?? []) acc.add(p)
-      for (const k of c.children ?? []) walk(k.id)
-      for (const j of c.jobs ?? []) if (j.target) walk(j.target)
-    }
-    for (const id of r.chain ?? []) walk(id)
-    if (acc.size > 0) out.set(r.id, [...acc].sort())
-  }
-  return out
-}
-
-/** R1: `store` is assigned only when a store was touched; absent otherwise. */
-function withStore<T extends LoaderResponse>(r: T): T {
-  const s = collectSnapshot()
-  if (s) (r as { store?: StoreSnapshot | null }).store = s
-  return r
-}
-
-// ---- handlers ----
-
-/** `parent`: the data the chain merged before the verdict. A notFound renders the route's
- * template (layouts included), so the layouts' data stays under the verdict's own keys. */
-function verdictJson(v: Verdict, parent: Record<string, unknown>): LoaderResponse {
-  if (v.status === 404) {
-    const own = v.data ?? {}
-    return { verdict: 'notFound', data: typeof own === 'object' && !Array.isArray(own) ? { ...parent, ...own } : own }
-  }
-  return { verdict: 'redirect', location: v.headers?.Location ?? '/', status: v.status }
-}
-
-export interface Handlers {
-  loader(req: LoaderRequest): Promise<LoaderResponse>
-  jobs(req: JobsRequest): Promise<JobsResponse>
-}
-
-/** `leaves` from `flattenRoutes` (ids must match the manifest's route ids); `jobs` the jobs
- * module; `manifest` supplies ssr `literals` (omit → no merge). */
-export function makeHandlers(opts: {
-  leaves: FlatRoute[]
-  jobs: JobsModule
-  manifest?: ManifestLike
-  /** `jobs.js` `stores` table (R2): C3 path -> module namespace. */
-  stores?: Record<string, object>
-}): Handlers {
-  const byId = new Map(opts.leaves.map((l) => [l.id, l]))
-  const literals = literalsIndex(opts.manifest)
-  const jobs = opts.jobs
-  const storeIdx = routeStoresIndex(opts.manifest)
-  const storeTable = opts.stores ?? {}
-
-  async function runJob(call: JobCall): Promise<JobResult> {
-    const owner = call.kind === 'ssr' ? (call.target ?? call.componentId) : call.componentId // D6
-    const fn = jobs[owner]?.[call.kind]
-    if (typeof fn !== 'function') return { id: call.id, error: `no ${call.kind} job for component ${owner}` }
-    try {
-      let props = call.inputs
-      if (call.kind === 'ssr') {
-        const jid = jobIdOf(call)
-        const lit = jid === undefined ? undefined : literals.get(`${call.componentId}/${jid}`)
-        if (lit) props = { ...(props ?? {}), ...lit }
-        // Precompute runs outside any scope (D8); ssr runs in a scope seeded from `__store`, which props never see.
-        const seed = (props?.__store ?? null) as StoreSnapshot | null
-        if (props && '__store' in props) {
-          const { __store: _, ...rest } = props
-          props = rest
-        }
-        const p = props
-        return { id: call.id, value: await runInStoreContext(() => fn(p), seed) }
-      }
-      return { id: call.id, value: await fn(props) }
-    } catch (e) {
-      return { id: call.id, error: String(e) }
-    }
-  }
-
-  return {
-    // 0.1.x `runNativeChainLoaders`: root → leaf, flat merge (later keys win), first verdict stops
-    // (a notFound keeps what the chain merged so far: verdictJson).
-    async loader(req) {
-      const leaf = byId.get(req.routeId)
-      if (!leaf) return { error: `unknown routeId ${req.routeId}` }
-      // One object for the whole chain: each level's keys are assigned INTO it (later keys win,
-      // first-seen key order — what `{...merged, ...r}` produced) instead of re-spreading every
-      // key once per level (M3-P P1). `merged` is fresh per call; a loader's own object is never
-      // written to. Null prototype: with no `__proto__` setter to hit, an own "__proto__" key in a
-      // loader's data is assigned as data, as the spread copied it.
-      return runInStoreContext(async () => {
-        const merged: Record<string, unknown> = Object.create(null)
-        try {
-          const touch = storeIdx.get(req.routeId)
-          if (touch) touchStores(touch, storeTable)
-          for (const node of leaf.chain) {
-            if (!node.loader) continue
-            let r: unknown
-            try {
-              r = await node.loader({ params: req.params, path: req.path, req: req.req })
-            } catch (e) {
-              if (isHttpErrorTrigger(e)) return { verdict: 'httpError', status: e.status, body: e.body } as LoaderResponse
-              throw e
-            }
-            if (isVerdict(r)) {
-              const v = verdictJson(r, merged)
-              return 'verdict' in v && v.verdict === 'notFound' ? withStore(v) : v
-            }
-            if (r && typeof r === 'object') Object.assign(merged, r)
-          }
-          return withStore({ ok: true, data: merged } as LoaderResponse)
-        } catch (e) {
-          return { error: String(e) } as LoaderResponse
-        }
-      })
-    },
-    // One request carries every job of the page; a per-job failure keeps the other results.
-    async jobs(req) {
-      return { results: await Promise.all((req.jobs ?? []).map(runJob)) }
-    },
-  }
-}
-
 /** The tsfn callback for `registerWorker`. Never rejects: a parse error, an unknown kind or a
  * throwing handler is written to the slot as `{error}`. A loader request with `plan: true` whose
  * chain answered `ok` is planned in the same call (`plan`, the napi `planJobs` by default — the
@@ -269,6 +48,7 @@ export function makeHandlers(opts: {
 export function makeDispatch(h: Handlers, view: Uint8Array, slots: number, plan: PlanJobs = planJobs) {
   return async (kind: string, requestJson: string, slot: number): Promise<number> => {
     if (kind === 'fetch') return runFetch(requestJson, view, slot, slots)
+    if (kind === 'cache') return runCache(requestJson, view, slot, slots, cacheHeapIo, cacheDeps)
     let out: unknown
     try {
       const req = JSON.parse(requestJson)
@@ -292,6 +72,31 @@ export function makeDispatch(h: Handlers, view: Uint8Array, slots: number, plan:
   }
 }
 
+// ---- cache adapter (the `cache` call kind) ----
+
+const cacheHeapIo: HeapIo = { takeBody: (slot) => takeFetchBody(slot), putReply: (slot, body) => putFetchReply(slot, body) }
+const count = (name: string) => void cacheL2Count(name)
+let cacheDeps: CacheBridgeDeps = { store: undefined, getTimeoutMs: 50, maxBodyBytes: 1_048_576, count }
+
+/** The `cache` call's store (tests; `startWorker` sets it from `manifest.cache`). */
+export function setCacheBridge(d: CacheBridgeDeps): void {
+  cacheDeps = d
+}
+
+/** Load `manifest.cache`'s adapter in this worker (R8): a custom module from dist, a built-in from the
+ * app root; `init`, then `cache.invalidate` publishes through it. Worker 0 also subscribes after
+ * registering (R10). */
+async function startCacheAdapter(m: CacheManifest, dist: string, appDir: string, workerId: number) {
+  const { loadAdapter } = await import('./cache-adapter/load')
+  const { setCacheRuntime } = await import('./cache-adapter/runtime')
+  const adapter = await loadAdapter(m, 'bun', (spec, builtin) => import(builtin ? Bun.resolveSync(spec, appDir) : join(dist, spec)), process.env)
+  await adapter.init?.({ namespace: m.namespace, buildId: m.buildId, runtime: 'bun', workerId })
+  const origin = process.env.BRUST_CACHE_ORIGIN || crypto.randomUUID()
+  setCacheRuntime({ adapter, origin, defer: (p) => void p.catch(() => {}), count, replay: (args, seq) => void cacheReplay(args, seq) })
+  setCacheBridge({ store: adapter.store, getTimeoutMs: m.getTimeoutMs, maxBodyBytes: m.maxBodyBytes, count })
+  return { adapter, origin }
+}
+
 // ---- worker entry ----
 
 export const SLOT_BYTES = 256 * 1024
@@ -318,7 +123,7 @@ export async function startWorker(opts: StartWorkerOptions = {}): Promise<number
   const dist = resolve(env.BRUST_DIST_DIR ?? 'dist')
   const entry = env.BRUST_APP_ENTRY
   if (!entry) throw new Error('BRUST_APP_ENTRY is not set')
-  const manifest = (await Bun.file(join(dist, 'manifest.json')).json()) as ManifestLike
+  const manifest = (await Bun.file(join(dist, 'manifest.json')).json()) as ManifestLike & { cache?: CacheManifest | null }
   const app = await import(resolve(entry))
   const routes = (app.routes ?? app.default) as Route[] | undefined
   if (!Array.isArray(routes)) throw new Error(`${entry} exports no routes (export const routes or default)`)
@@ -330,6 +135,8 @@ export async function startWorker(opts: StartWorkerOptions = {}): Promise<number
     setActionsApp(await loadActionsApp(join(dist, manifest.actions.entry), manifest.actions.prefix))
     setActionsLimits({ maxResponseBytes: manifest.actions.maxResponseBytes ?? DEFAULT_MAX_RESPONSE_BYTES })
   }
+  const workerId = Number.parseInt(env.BRUST_WORKER_ID ?? '0', 10) || 0
+  const l2 = manifest.cache ? await startCacheAdapter(manifest.cache, dist, dirname(resolve(entry)), workerId) : null
   sab = opts.sab ?? new SharedArrayBuffer(SLOT_BYTES * slots)
   view = new Uint8Array(sab)
   const handlers = makeHandlers({
@@ -338,7 +145,12 @@ export async function startWorker(opts: StartWorkerOptions = {}): Promise<number
     manifest,
     stores: (jobsMod.stores ?? {}) as Record<string, object>,
   })
-  return registerWorker(view, slots, makeDispatch(handlers, view, slots))
+  const id = registerWorker(view, slots, makeDispatch(handlers, view, slots))
+  if (l2 && env.BRUST_WORKER_ID === '0') {
+    const { startSubscriber } = await import('./cache-adapter/runtime')
+    await startSubscriber(l2.adapter, l2.origin, { replay: (args, seq) => void cacheReplay(args, seq), clear: () => void cacheClear(), count })
+  }
+  return id
 }
 
 // Auto-start only inside a Bun `Worker` spawned by `run()` (BRUST_WORKER_ID set). Not