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

package/src/shadcn/registry.ts

@@ -0,0 +1,149 @@
+// F228: a registry URL given to `brust shadcn init` names a third-party item that declares its own file targets, known
+// only once the item is fetched. This fetches the item JSON BEFORE the shadcn CLI is spawned (https only, a size cap, a
+// timeout, redirects followed by hand and only to https) and checks every path it can make the CLI write. The command
+// then hands the CLI the file it checked, not the URL, so the item cannot change between the check and the write.
+
+/** The most bytes of item JSON read; a bigger answer is refused. */
+export const ITEM_MAX_BYTES = 1024 * 1024
+/** The whole fetch (redirects included) gets this long. */
+export const ITEM_TIMEOUT_MS = 15_000
+/** Redirects followed by hand; each target must be https. */
+export const MAX_REDIRECTS = 3
+
+export interface FetchOptions {
+  /** URL schemes allowed for the request and every redirect. Default `https:` only; a test passes `http:` for a local server. */
+  schemes?: string[]
+  maxBytes?: number
+  timeoutMs?: number
+}
+
+/** Fetches `url` and returns the body text, or throws an `Error` whose message is the reason it was refused. */
+export async function fetchRegistryItem(url: string, o: FetchOptions = {}): Promise<string> {
+  const schemes = o.schemes ?? ['https:']
+  const maxBytes = o.maxBytes ?? ITEM_MAX_BYTES
+  const signal = AbortSignal.timeout(o.timeoutMs ?? ITEM_TIMEOUT_MS)
+  let cur = url
+  try {
+    for (let hop = 0; ; hop++) {
+      let u: URL
+      try {
+        u = new URL(cur)
+      } catch {
+        throw new Error(`${cur} is not a URL`)
+      }
+      if (!schemes.includes(u.protocol)) throw new Error(`${cur} is not an ${schemes.join(' or ').replace(/:/g, '')} URL`)
+      if (u.username !== '' || u.password !== '') throw new Error(`${u.origin}${u.pathname} carries credentials in the URL`)
+      const res = await fetch(u, { redirect: 'manual', signal, headers: { accept: 'application/json' } })
+      if (res.status >= 300 && res.status < 400) {
+        const next = res.headers.get('location')
+        await res.body?.cancel()
+        if (!next) throw new Error(`${cur} answered ${res.status} with no Location`)
+        if (hop >= MAX_REDIRECTS) throw new Error(`${url} redirects more than ${MAX_REDIRECTS} times`)
+        cur = new URL(next, u).toString() // the next loop turn refuses a non-https target
+        continue
+      }
+      if (!res.ok) {
+        await res.body?.cancel()
+        throw new Error(`${cur} answered HTTP ${res.status}`)
+      }
+      const declared = Number(res.headers.get('content-length'))
+      if (Number.isFinite(declared) && declared > maxBytes) {
+        await res.body?.cancel()
+        throw new Error(`${cur} is ${declared} bytes; the limit is ${maxBytes}`)
+      }
+      const reader = res.body?.getReader()
+      if (!reader) return ''
+      const chunks: Uint8Array[] = []
+      let size = 0
+      for (;;) {
+        const { done, value } = await reader.read()
+        if (done) break
+        size += value.length
+        if (size > maxBytes) {
+          await reader.cancel()
+          throw new Error(`${cur} is bigger than the limit of ${maxBytes} bytes`)
+        }
+        chunks.push(value)
+      }
+      return new TextDecoder('utf-8', { fatal: true }).decode(Buffer.concat(chunks))
+    }
+  } catch (e) {
+    if (signal.aborted) throw new Error(`${url} did not answer within ${(o.timeoutMs ?? ITEM_TIMEOUT_MS) / 1000} s`)
+    throw e instanceof Error ? e : new Error(String(e))
+  }
+}
+
+/** True for a path that is not a plain relative path: absolute, a drive, a backslash, a NUL, a control character or `..`. */
+export function unsafeRel(p: string): boolean {
+  return p === '' || p.startsWith('/') || /^[a-zA-Z]:/.test(p) || p.includes('\\') || /[\x00-\x1f]/.test(p) || p.split('/').some((s) => s === '..') || (p.includes('%') && /%2e|%2f|%5c|%00/i.test(p))
+}
+
+export interface VettedItem {
+  /** Project-relative paths the CLI may write for this item, beyond the alias directories (checked for symlinks). */
+  paths: string[]
+}
+
+const PLAIN_NAME = /^[a-z0-9][a-z0-9-]*$/
+
+/** The top-level keys of an item in the pinned registry schema (`@shadcn/registry` 0.1.3). Allowlist, not denylist: a key
+ *  this does not name (`font`, which makes the CLI write the CSS entry and a layout file, or one a later schema adds) is a
+ *  refusal, because the CLI could write something this never judged. */
+const ITEM_KEYS = new Set(['$schema', 'extends', 'name', 'type', 'title', 'author', 'description', 'dependencies', 'devDependencies', 'registryDependencies', 'files', 'tailwind', 'cssVars', 'css', 'envVars', 'meta', 'docs', 'categories'])
+/** Item types whose files the CLI rewrites to a framework path (`registry:page`) or whose write set is not judged (`registry:font`). */
+const REFUSED_TYPES = new Set(['registry:font', 'registry:page'])
+
+/**
+ * Judges item JSON: the file targets it declares and the other things it makes the CLI write or fetch. Returns the
+ * paths to check for symlinks, or the reason it is refused. Fail closed: anything it cannot judge is a refusal.
+ */
+export function vetItem(text: string, cssEntry: string): VettedItem | { error: string } {
+  let item: unknown
+  try {
+    item = JSON.parse(text)
+  } catch {
+    return { error: 'is not valid JSON' }
+  }
+  if (typeof item !== 'object' || item === null || Array.isArray(item)) return { error: 'is not a JSON object' }
+  const o = item as Record<string, unknown>
+  if (o.type !== undefined && (typeof o.type !== 'string' || REFUSED_TYPES.has(o.type))) return { error: `is of type ${JSON.stringify(o.type)}, whose files the CLI places by rules this check does not model` }
+  const unknown = Object.keys(o).find((k) => !ITEM_KEYS.has(k))
+  if (unknown !== undefined) return { error: `has the key ${JSON.stringify(unknown)}, which this check does not know; it may make the CLI write files that cannot be checked` }
+  const paths: string[] = []
+  if (o.files !== undefined) {
+    if (!Array.isArray(o.files)) return { error: '"files" is not an array' }
+    for (const f of o.files) {
+      if (typeof f !== 'object' || f === null) return { error: 'has a file entry that is not an object' }
+      const { path, target } = f as { path?: unknown; target?: unknown }
+      if (path !== undefined && typeof path !== 'string') return { error: 'has a file with a "path" that is not a string' }
+      if (target !== undefined && typeof target !== 'string') return { error: 'has a file with a "target" that is not a string' }
+      if (typeof path === 'string' && unsafeRel(path)) return { error: `declares the file path ${JSON.stringify(path)}, which is not a plain path inside the project` }
+      if (typeof target === 'string' && target !== '') {
+        // The CLI's own rules (resolveFilePath): `~/x` is project-relative; `@components|ui|lib|hooks/x` is inside that alias
+        // directory (scanned already); any other target is joined to the project root, once as written and, in a `src/`
+        // project, under `src/` (it drops one `src/` from the target either way). All of them are checked.
+        const t = target.startsWith('~/') ? target.slice(2) : target
+        const alias = /^@(components|ui|lib|hooks)\/(.+)$/.exec(t)
+        if (alias) {
+          if (unsafeRel(alias[2]!)) return { error: `declares the file target ${JSON.stringify(target)}, which is not a plain path inside the project` }
+        } else {
+          const rel = t.replace(/^@([^/]+)\//, '$1/')
+          if (unsafeRel(rel)) return { error: `declares the file target ${JSON.stringify(target)}, which is not a plain path inside the project` }
+          const bare = rel.replace('src/', '')
+          paths.push(rel, bare, `src/${bare}`)
+        }
+      }
+    }
+  }
+  // what else the CLI writes: the Tailwind CSS entry (css, cssVars), env files (envVars)
+  if (o.css !== undefined || o.cssVars !== undefined || o.tailwind !== undefined) paths.push(cssEntry)
+  if (o.envVars !== undefined) paths.push('.env', '.env.local')
+  // dependencies on other items the CLI would fetch after this check (a `config` that would merge into components.json is an unknown key, refused above)
+  const deps = [...(Array.isArray(o.registryDependencies) ? o.registryDependencies : o.registryDependencies === undefined ? [] : [null]), ...(o.extends === undefined ? [] : [o.extends])]
+  for (const d of deps) {
+    if (typeof d !== 'string') return { error: 'has a registryDependencies / extends entry that is not a string' }
+    if (!PLAIN_NAME.test(d)) {
+      return { error: `depends on ${JSON.stringify(d)}, which the CLI would fetch after this check; pass that URL to the command as its own argument so it is checked too` }
+    }
+  }
+  return { paths }
+}

package/src/worker.ts

@@ -1,274 +1,92 @@
 // 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 { appendFileSync } from 'node:fs'
+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, type SsgRecord, toJson } from './handlers'
+import { cacheClear, cacheL2Count, cacheReplay, planJobs, planJobsBuf, putFetchReply, registerWorker, takeFetchBody } from './native'
+import { installServerOnlyRuntime } from './build/server-only'
+import { flattenRoutes, type Route } from './routes'
 
-installServerResolver(getServerInstance)
+export * from './handlers'
 
-// ---- 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 }
+// ---- SAB slot writer ----
 
-export interface JobsResponse {
-  results: JobResult[]
-}
+const enc = new TextEncoder()
 
-/** 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> }>
+/** L10: the default `maxLoaderResponseBytes` (config.ts keeps the range). */
+export const DEFAULT_MAX_LOADER_RESPONSE_BYTES = 8_388_608
 
-/** 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
+/** L10: a reply too large for the slot crosses by heap: `HeapIo.putReply` hands Rust the bytes, and the slot holds
+ * the 5-byte marker `[0x00][u32 LE n]` (JSON never starts with 0x00). `cap` = `maxLoaderResponseBytes`. */
+export const HEAP_MARKER_BYTES = 5
+export interface HeapReply {
+  io: HeapIo
+  /** `planJobsBuf` (napi): plan a loader response handed over directly. */
+  planBuf: (slot: number, buf: Uint8Array) => string
+  /** Default: the worker's `maxLoaderResponseBytes` (env `BRUST_MAX_LOADER_RESPONSE_BYTES`, 8 MiB). */
+  cap?: number
 }
-
-// ---- SAB slot writer ----
-
-const enc = new TextEncoder()
+const nativeHeap: HeapReply = { io: cacheHeapIo(), planBuf: (slot, buf) => planJobsBuf(slot, buf) }
+let loaderCap = DEFAULT_MAX_LOADER_RESPONSE_BYTES
 
 /** Writes `json` as UTF-8 at the start of `slot`'s sub-region `[slot*sub, slot*sub+sub)`,
  * `sub = floor(view.byteLength / slots)`; returns the byte length (> 0, ≤ sub). ONE copy: the
  * encoder writes straight into the slot (M3-P P1); it stops at the last whole code point that
  * fits, so `read < json.length` means "did not fit" and the neighbouring slot is never touched.
- * A response that does not fit is replaced by a small `{"error":"response too large: <n> > <sub>"}`
- * (`n` = its exact UTF-8 length, computed only on this path). */
-export function writeSlot(view: Uint8Array, slot: number, slots: number, json: string): number {
+ * A response that does not fit goes by heap when `io` and `cap` are given (L10): encoded once, handed to
+ * Rust with `io.putReply`, and the slot holds the 5-byte marker. Over `cap` (or declined), or with no `io`, it is
+ * replaced by a small `{"error":"response too large: <n> > <limit>"}` (`n` = its exact UTF-8 length, computed
+ * only on this path). */
+export function writeSlot(view: Uint8Array, slot: number, slots: number, json: string, io?: HeapIo, cap?: number): number {
   const sub = Math.floor(view.byteLength / Math.max(1, slots))
   const dst = view.subarray(slot * sub, slot * sub + sub)
   const r = enc.encodeInto(json, dst)
   if (r.read === json.length) return r.written
-  const err = JSON.stringify({ error: `response too large: ${Buffer.byteLength(json)} > ${sub}` })
+  let why = `response too large: ${Buffer.byteLength(json)} > ${sub}`
+  if (io && cap !== undefined && sub >= HEAP_MARKER_BYTES) {
+    const bytes = enc.encode(json)
+    const n = heapMarker(dst, slot, bytes, io, cap)
+    if (n > 0) return n
+    // Name the real reason: over the cap, or a put Rust declined while under it (idle slot, a second put).
+    why = bytes.length > cap ? `response too large: ${bytes.length} > ${cap} (maxLoaderResponseBytes)` : `heap reply declined: ${bytes.length} bytes did not fit the ${sub}-byte slot and Rust refused the handover`
+  }
+  const err = JSON.stringify({ error: why })
   const e = enc.encodeInto(err, dst)
   if (e.read === err.length) return e.written
   // Not even the message fits: the first `sub` bytes of a fixed one (ASCII, so byte = char).
   return enc.encodeInto('{"error":"too large"}', dst).written
 }
 
+/** Hand `bytes` to Rust and write the marker at `dst`; 0 when over `cap` or Rust declined. */
+function heapMarker(dst: Uint8Array, slot: number, bytes: Uint8Array, io: HeapIo, cap: number): number {
+  if (bytes.length > cap || !io.putReply(slot, bytes)) return 0
+  dst[0] = 0
+  new DataView(dst.buffer, dst.byteOffset + 1, 4).setUint32(0, bytes.length, true)
+  return HEAP_MARKER_BYTES
+}
+
 /** `planJobs` (napi): the misses' JobsRequest JSON, '' (every job hit) or PLAN_DECLINED. */
 export type PlanJobs = (slot: number, len: number) => string
 /** `planJobs` declined: the loader response already in the slot is the answer (Rust plans after the call). */
 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
- * addon is touched only then). */
-export function makeDispatch(h: Handlers, view: Uint8Array, slots: number, plan: PlanJobs = planJobs) {
+ * addon is touched only then). A loader/jobs/planned reply that does not fit the slot crosses by heap
+ * (`heap`, the napi addon by default; L10). */
+export function makeDispatch(h: Handlers, view: Uint8Array, slots: number, plan: PlanJobs = planJobs, heap: HeapReply = nativeHeap) {
+  const cap = () => heap.cap ?? loaderCap
   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)
@@ -278,9 +96,20 @@ export function makeDispatch(h: Handlers, view: Uint8Array, slots: number, plan:
           // One round trip (M3-P P6): the ctx goes to Rust through this slot, synchronously, and only
           // the jobs Rust found missing run here; the final answer replaces it in the same slot.
           const json = toJson(out)
-          const n = writeSlot(view, slot, slots, json)
-          const misses = plan(slot, n)
-          if (misses === PLAN_DECLINED) return n
+          const sub = Math.floor(view.byteLength / Math.max(1, slots))
+          const dst = view.subarray(slot * sub, slot * sub + sub)
+          const w = enc.encodeInto(json, dst)
+          let misses: string
+          if (w.read === json.length) {
+            misses = plan(slot, w.written)
+            if (misses === PLAN_DECLINED) return w.written
+          } else {
+            // L10: too large for the slot — plan from the bytes directly; a declined plan hands them over as the answer.
+            const bytes = enc.encode(json)
+            if (bytes.length > cap()) return writeSlot(view, slot, slots, json, heap.io, cap())
+            misses = heap.planBuf(slot, bytes)
+            if (misses === PLAN_DECLINED) return writeSlot(view, slot, slots, json, heap.io, cap())
+          }
           out = misses === '' ? PLANNED : { planned: true, results: (await h.jobs(JSON.parse(misses))).results }
         }
       } else if (kind === 'jobs') out = await h.jobs(req)
@@ -288,16 +117,51 @@ export function makeDispatch(h: Handlers, view: Uint8Array, slots: number, plan:
     } catch (e) {
       out = { error: String(e) }
     }
-    return writeSlot(view, slot, slots, toJson(out))
+    return writeSlot(view, slot, slots, toJson(out), heap.io, cap())
   }
 }
 
+// ---- cache adapter (the `cache` call kind) ----
+
+function cacheHeapIo(): HeapIo {
+  return { 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 }
+}
+
+// ---- static output (gaps round R9.5) ----
+
+/** Appends each record as one JSON line to `file` (every worker of the render appends to it). */
+function ssgLog(file: string): (r: SsgRecord) => void {
+  return (r) => appendFileSync(file, `${JSON.stringify(r)}\n`)
+}
+
 // ---- worker entry ----
 
+/** The default response slot (`slotBytes`, config.ts: 64 KiB..16 MiB). */
 export const SLOT_BYTES = 256 * 1024
 
 export interface StartWorkerOptions {
-  /** The response buffer to register (`SLOT_BYTES * slots` bytes). `run()` allocates it on the
+  /** The response buffer to register (`slotBytes * slots` bytes). `run()` allocates it on the
    * MAIN thread and keeps it for the process lifetime, passing it as `workerData.sab`: the Rust
    * dispatcher holds a raw pointer into it until the process exits, so its backing store must not
    * die with this worker (`crates/brust-napi/src/dispatch.rs` BufPtr). Absent (tests, a worker
@@ -316,11 +180,19 @@ export async function startWorker(opts: StartWorkerOptions = {}): Promise<number
   const env = process.env
   const slots = Math.max(1, Number.parseInt(env.BRUST_RENDER_SLOTS ?? '1', 10) || 1)
   const dist = resolve(env.BRUST_DIST_DIR ?? 'dist')
-  const entry = env.BRUST_APP_ENTRY
+  // L16 R16.3: an actions-only dist has no routes module (so no BRUST_APP_ENTRY either).
+  const manifestFile = join(dist, 'manifest.json')
+  const hasManifest = await Bun.file(manifestFile).exists()
+  const actionsOnly = hasManifest && !env.BRUST_APP_ENTRY && ((await Bun.file(manifestFile).json()) as { actions_only?: boolean }).actions_only === true
+  const entry = env.BRUST_APP_ENTRY ?? (actionsOnly ? join(dist, 'index.js') : undefined)
   if (!entry) throw new Error('BRUST_APP_ENTRY is not set')
-  const manifest = (await Bun.file(join(dist, 'manifest.json')).json()) as ManifestLike
-  const app = await import(resolve(entry))
-  const routes = (app.routes ?? app.default) as Route[] | undefined
+  const manifest = (await Bun.file(manifestFile).json()) as ManifestLike & { cache?: CacheManifest | null; actions_only?: boolean }
+  let routes: Route[] | undefined = []
+  if (!manifest.actions_only) {
+    installServerOnlyRuntime()
+    const app = await import(resolve(entry))
+    routes = (app.routes ?? app.default) as Route[] | undefined
+  }
   if (!Array.isArray(routes)) throw new Error(`${entry} exports no routes (export const routes or default)`)
   const jobsMod = await import(join(dist, manifest.jobs_module ?? 'jobs.js'))
   const jobs = (jobsMod.default ?? jobsMod) as JobsModule
@@ -330,15 +202,25 @@ 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 })
   }
-  sab = opts.sab ?? new SharedArrayBuffer(SLOT_BYTES * slots)
+  loaderCap = Number.parseInt(env.BRUST_MAX_LOADER_RESPONSE_BYTES ?? '', 10) || DEFAULT_MAX_LOADER_RESPONSE_BYTES
+  const slotBytes = Number.parseInt(env.BRUST_SLOT_BYTES ?? '', 10) || SLOT_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(slotBytes * slots)
   view = new Uint8Array(sab)
   const handlers = makeHandlers({
     leaves: flattenRoutes(routes).leaves,
     jobs,
     manifest,
     stores: (jobsMod.stores ?? {}) as Record<string, object>,
+    ...(env.BRUST_SSG === '1' && env.BRUST_SSG_LOG ? { ssg: ssgLog(env.BRUST_SSG_LOG) } : {}),
   })
-  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