brustjs 0.1.50-alpha → 0.1.51-alpha

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "brustjs",
-  "version": "0.1.50-alpha",
+  "version": "0.1.51-alpha",
   "description": "Bun + Rust SSR framework — React on the server, Rust everywhere else (napi cdylib + per-worker SharedArrayBuffer).",
   "license": "MIT",
   "repository": {
@@ -41,12 +41,12 @@
     "typescript": "^6.0.3"
   },
   "optionalDependencies": {
-    "brustjs-darwin-x64": "0.1.50-alpha",
-    "brustjs-darwin-arm64": "0.1.50-alpha",
-    "brustjs-linux-x64-gnu": "0.1.50-alpha",
-    "brustjs-linux-arm64-gnu": "0.1.50-alpha",
-    "brustjs-linux-x64-musl": "0.1.50-alpha",
-    "brustjs-linux-arm64-musl": "0.1.50-alpha"
+    "brustjs-darwin-x64": "0.1.51-alpha",
+    "brustjs-darwin-arm64": "0.1.51-alpha",
+    "brustjs-linux-x64-gnu": "0.1.51-alpha",
+    "brustjs-linux-arm64-gnu": "0.1.51-alpha",
+    "brustjs-linux-x64-musl": "0.1.51-alpha",
+    "brustjs-linux-arm64-musl": "0.1.51-alpha"
   },
   "peerDependencies": {
     "react": "^19.2.6",
@@ -71,18 +71,40 @@
     "zod": "^4.4.3"
   },
   "type": "module",
-  "types": "./runtime/index.d.ts",
+  "types": "./types/index.d.ts",
   "exports": {
-    ".": "./runtime/index.ts",
-    "./routes": "./runtime/routes.ts",
-    "./client": "./runtime/client/index.ts",
-    "./create": "./runtime/create.ts",
-    "./store": "./runtime/store/index.ts",
-    "./native": "./runtime/native/index.ts",
-    "./navigation": "./runtime/navigation/index.ts"
+    ".": {
+      "types": "./types/index.d.ts",
+      "default": "./runtime/index.ts"
+    },
+    "./routes": {
+      "types": "./types/routes.d.ts",
+      "default": "./runtime/routes.ts"
+    },
+    "./client": {
+      "types": "./types/client/index.d.ts",
+      "default": "./runtime/client/index.ts"
+    },
+    "./create": {
+      "types": "./types/create.d.ts",
+      "default": "./runtime/create.ts"
+    },
+    "./store": {
+      "types": "./types/store/index.d.ts",
+      "default": "./runtime/store/index.ts"
+    },
+    "./native": {
+      "types": "./types/native/index.d.ts",
+      "default": "./runtime/native/index.ts"
+    },
+    "./navigation": {
+      "types": "./types/navigation/index.d.ts",
+      "default": "./runtime/navigation/index.ts"
+    }
   },
   "files": [
     "runtime",
+    "types",
     "!runtime/node_modules",
     "!runtime/package.json",
     "!runtime/*.node",
@@ -100,6 +122,8 @@
   "scripts": {
     "build": "cd runtime && bun run build",
     "build:debug": "cd runtime && bun run build:debug",
+    "build:dts": "tsc -p tsconfig.dts.json; bun scripts/assert-dts.ts",
+    "prepack": "bun run build:dts",
     "test": "bun test tests/integration.test.ts",
     "dev": "bun runtime/cli/index.ts dev example/pokedex/index.ts",
     "docs:dev": "cd example/docs && bun ../../runtime/cli/index.ts dev index.ts",

package/runtime/cache-sync.ts

@@ -0,0 +1,291 @@
+// R9 cross-process cache invalidation. Publishes cache.invalidate() calls to a
+// redis/dragonfly pub/sub channel and applies messages from peers to the local
+// process-global Rust caches. Pure TS — Bun's native RedisClient, zero deps.
+//
+// Bun 1.4.0 RedisClient facts (verified empirically — do not "simplify"):
+// - subscribe(channel, cb): cb receives (message, channel). Errors do NOT come
+//   through the callback; disconnects fire client.onclose.
+// - Against an unreachable host, connect()/subscribe() return promises that
+//   NEVER settle and onclose never fires → every connect must be raced
+//   against a timeout or a down redis silently disables the feature.
+// - No auto-resubscribe after a drop → onclose re-creates the client.
+import { RedisClient } from 'bun'
+import type { InvalidateArgs } from './cache.ts'
+import * as native from './index.js'
+
+/** Public wire contract (documented for external publishers like studio):
+ * `{ "v": 1, "sender": "<uuid>", "key": "...", "tags": ["..."],
+ *    "path": "...", "method": "GET" }` — all invalidation fields optional,
+ * `sender` may be omitted (never matches our token, always applied). */
+export interface CacheSyncMessage {
+  v: 1
+  sender?: string
+  key?: string
+  tags?: string[]
+  path?: string
+  method?: string
+}
+
+export const CHANNEL_DEFAULT = 'brust:cache:invalidate'
+const CONNECT_TIMEOUT_MS = 5_000
+const BACKOFF_BASE_MS = 1_000
+const BACKOFF_MAX_MS = 30_000
+const WARN_THROTTLE_MS = 30_000
+
+// Per-isolate state. The subscriber lives in the main isolate only (run()
+// wires it); the publisher is lazy per isolate (workers publish from
+// loaders/actions). Rust caches are process-global, so applying here reaches
+// every worker implicitly.
+let started = false
+let stopped = false
+let subscriber: RedisClient | null = null
+let publisher: RedisClient | null = null
+let publisherUrl: string | null = null
+let retryTimer: ReturnType<typeof setTimeout> | null = null
+let backoffMs = BACKOFF_BASE_MS
+const lastWarnAt = new Map<string, number>()
+
+/** Injectable publish seam so unit tests never construct a RedisClient. */
+export interface CacheSyncTransport {
+  publish(channel: string, message: string): Promise<unknown>
+}
+let testTransport: CacheSyncTransport | null = null
+export function __setTransportForTest(t: CacheSyncTransport | null): void {
+  testTransport = t
+}
+
+/** The redis URL may carry credentials (`redis://:pass@host:port/db`). Every
+ * log line that mentions the target MUST go through this — host:port only. */
+export function redactUrl(url: string): string {
+  try {
+    const u = new URL(url)
+    return `${u.hostname}:${u.port || '6379'}`
+  } catch {
+    return '<unparseable redis url>'
+  }
+}
+
+/** Error messages from RedisClient may embed the raw connection string —
+ * scrub the configured URL (and any redis://user:pass@ userinfo) before a
+ * message reaches the log. */
+function scrubErrorMessage(e: unknown, url: string): string {
+  const raw = String((e as Error)?.message ?? e)
+  return raw
+    .replaceAll(url, redactUrl(url))
+    .replace(/rediss?:\/\/[^@\s]+@/gi, 'redis://<redacted>@')
+}
+
+/** Once per 30s per error kind — a down redis must not spam the log on every
+ * invalidate/retry. */
+function warnThrottled(kind: string, msg: string): void {
+  const now = Date.now()
+  const last = lastWarnAt.get(kind) ?? 0
+  if (now - last < WARN_THROTTLE_MS) return
+  lastWarnAt.set(kind, now)
+  console.warn(`[brust] ${msg}`)
+}
+
+/** Apply a parsed peer message to the local NAPI caches. Direct fan-out —
+ * NEVER via cache.invalidate, so a received message can never re-publish
+ * (no loop, even across misconfigured channels). Exported for tests. */
+export function applyCacheSyncMessage(msg: CacheSyncMessage): void {
+  if (msg === null || typeof msg !== 'object' || msg.v !== 1) {
+    warnThrottled('apply', 'cache-sync: dropping message with unsupported shape/version')
+    return
+  }
+  if (
+    msg.tags !== undefined &&
+    (!Array.isArray(msg.tags) || msg.tags.some((t) => typeof t !== 'string'))
+  ) {
+    warnThrottled('apply', 'cache-sync: dropping message — tags must be an array of strings')
+    return
+  }
+  for (const field of ['sender', 'key', 'path', 'method'] as const) {
+    if (msg[field] !== undefined && typeof msg[field] !== 'string') {
+      warnThrottled('apply', `cache-sync: dropping message — ${field} must be a string`)
+      return
+    }
+  }
+  // The publishing isolate already applied locally — skip our own messages.
+  if (msg.sender && msg.sender === process.env.BRUST_CACHE_SYNC_SENDER) {
+    return
+  }
+  // EXACT mirror of cache.invalidate's local NAPI fan-out (cache.ts). `?.`
+  // keeps a stale addon (built before a binding existed) a no-op.
+  ;(native as any).islandCacheInvalidate?.(msg.key, msg.tags)
+  ;(native as any).pageCacheInvalidate?.(msg.key, msg.tags)
+  ;(native as any).responseCacheInvalidate?.(msg.tags, msg.path, msg.method)
+}
+
+/** Publish an invalidation to peers. No-op when sync is not configured
+ * (BRUST_CACHE_SYNC_URL absent). Fire-and-forget: synchronous from the
+ * caller's view, failures warn (throttled) and never propagate — local
+ * invalidation must never depend on redis state. */
+export function publishCacheSync(args: InvalidateArgs): void {
+  // invalidate({}) is a deliberate local no-op — don't broadcast it either.
+  if (!args.key && (!args.tags || args.tags.length === 0) && !args.path) return
+  const url = process.env.BRUST_CACHE_SYNC_URL
+  if (!url) return
+  const channel = process.env.BRUST_CACHE_SYNC_CHANNEL || CHANNEL_DEFAULT
+
+  const msg: CacheSyncMessage = { v: 1 }
+  const sender = process.env.BRUST_CACHE_SYNC_SENDER
+  if (sender) msg.sender = sender
+  if (args.key) msg.key = args.key
+  if (args.tags && args.tags.length > 0) msg.tags = args.tags
+  if (args.path) msg.path = args.path
+  if (args.method) msg.method = args.method
+
+  try {
+    const transport = testTransport ?? getPublisher(url)
+    transport.publish(channel, JSON.stringify(msg)).catch((e) => {
+      // Heal the lazy client: a publisher that died (redis restart) would
+      // otherwise be returned forever by getPublisher — drop it so the next
+      // publish reconnects.
+      if (transport === publisher) {
+        try {
+          publisher?.close()
+        } catch {
+          // best-effort
+        }
+        publisher = null
+        publisherUrl = null
+      }
+      warnThrottled(
+        'publish',
+        `cache-sync: publish to ${redactUrl(url)} failed: ${scrubErrorMessage(e, url)}`,
+      )
+    })
+  } catch (e) {
+    warnThrottled(
+      'publish',
+      `cache-sync: publish to ${redactUrl(url)} failed: ${scrubErrorMessage(e, url)}`,
+    )
+  }
+}
+
+function getPublisher(url: string): CacheSyncTransport {
+  if (!publisher || publisherUrl !== url) {
+    try {
+      publisher?.close()
+    } catch {
+      // best-effort
+    }
+    publisher = new RedisClient(url)
+    publisherUrl = url
+  }
+  return publisher
+}
+
+/** Start the subscriber (main isolate only — run() guards; workers never call
+ * this). Idempotent; never throws. A down redis at boot logs a redacted warn
+ * and retries with capped exponential backoff — the server boots regardless. */
+export function startCacheSync(opts: { url: string; channel?: string }): void {
+  if (started) return
+  started = true
+  stopped = false
+  backoffMs = BACKOFF_BASE_MS
+  const channel = opts.channel || process.env.BRUST_CACHE_SYNC_CHANNEL || CHANNEL_DEFAULT
+  void attempt(opts.url, channel)
+}
+
+async function attempt(url: string, channel: string): Promise<void> {
+  if (stopped) return
+  const client = new RedisClient(url)
+  subscriber = client
+  let timeoutTimer: ReturnType<typeof setTimeout> | undefined
+  try {
+    // Race the subscribe against a timeout: against a down host the promise
+    // NEVER settles (see header) — without the race a down redis at boot
+    // would silently disable the feature forever. The no-op catch keeps a
+    // late loser settling AFTER the timeout from becoming an unhandled
+    // rejection.
+    const subscribed = client.subscribe(channel, onMessage)
+    subscribed.catch(() => {})
+    await Promise.race([
+      subscribed,
+      new Promise((_, reject) => {
+        timeoutTimer = setTimeout(() => reject(new Error('connect timeout')), CONNECT_TIMEOUT_MS)
+        timeoutTimer.unref?.()
+      }),
+    ])
+    // Identity guard: a slow connect can settle AFTER the timeout already
+    // scheduled a retry and a newer attempt replaced `subscriber` — this
+    // stale winner must stand down, not double-subscribe.
+    if (stopped || subscriber !== client) {
+      try {
+        client.close()
+      } catch {
+        // best-effort
+      }
+      return
+    }
+    backoffMs = BACKOFF_BASE_MS
+    // No auto-resubscribe after a drop (see header) — re-create the client.
+    client.onclose = () => {
+      if (!stopped && subscriber === client) scheduleRetry(url, channel)
+    }
+  } catch (e) {
+    try {
+      client.close()
+    } catch {
+      // best-effort
+    }
+    warnThrottled(
+      'connect',
+      `cache-sync: redis unreachable at ${redactUrl(url)}, retrying (${scrubErrorMessage(e, url)})`,
+    )
+    if (subscriber === client) scheduleRetry(url, channel)
+  } finally {
+    if (timeoutTimer !== undefined) clearTimeout(timeoutTimer)
+  }
+}
+
+function scheduleRetry(url: string, channel: string): void {
+  if (stopped || retryTimer) return
+  retryTimer = setTimeout(() => {
+    retryTimer = null
+    void attempt(url, channel)
+  }, backoffMs)
+  // A dead redis must never hold the process open past drain.
+  retryTimer.unref?.()
+  backoffMs = Math.min(backoffMs * 2, BACKOFF_MAX_MS)
+}
+
+function onMessage(message: string, _channel: string): void {
+  let parsed: CacheSyncMessage
+  try {
+    parsed = JSON.parse(message)
+  } catch {
+    warnThrottled('parse', 'cache-sync: dropping unparseable message')
+    return
+  }
+  applyCacheSyncMessage(parsed)
+}
+
+/** Shutdown/test hook: stop retries, close both clients, reset state so tests
+ * can restart. Wired into gracefulExit so backoff timers can't fire between
+ * drain and exit. */
+export function stopCacheSync(): void {
+  stopped = true
+  started = false
+  if (retryTimer) {
+    clearTimeout(retryTimer)
+    retryTimer = null
+  }
+  try {
+    subscriber?.close()
+  } catch {
+    // best-effort
+  }
+  subscriber = null
+  try {
+    publisher?.close()
+  } catch {
+    // best-effort
+  }
+  publisher = null
+  publisherUrl = null
+  backoffMs = BACKOFF_BASE_MS
+  lastWarnAt.clear()
+}

package/runtime/cache.ts

@@ -1,5 +1,6 @@
 // Dev-facing island ISR cache control. Invalidation crosses to the Rust-side
 // store (shared across the worker pool) via NAPI. Call from action/api/loader.
+import { publishCacheSync } from './cache-sync.ts'
 import * as native from './index.js'
 
 export interface InvalidateArgs {
@@ -28,5 +29,8 @@ export const cache = {
     // Fan out to the L1 response cache by tag (route must declare cache.tags)
     // and/or by path. `?.` keeps a stale addon a no-op.
     ;(native as any).responseCacheInvalidate?.(args.tags, args.path, args.method)
+    // R9: propagate to peer processes when cache-sync is configured (no-op
+    // otherwise). Fire-and-forget — local invalidation never depends on redis.
+    publishCacheSync(args)
   },
 }

package/runtime/cli/dev.ts

@@ -100,6 +100,13 @@ export async function runDev(args: string[]): Promise<void> {
     }[],
     outDir: jinjaDir,
     repoRoot: REPO_ROOT,
+    // R14 — dev-loop incremental compile: per-route content-hash memo over the
+    // resolved compileJsx inputs (route source + transitive local imports +
+    // lucide/directive env); an unchanged route skips recompile on hot reload.
+    // The boot emit below is incremental too — first run always misses (memo is
+    // per-process), so it just SEEDS the memo and the very first edit benefits.
+    // `brust build` never sets this flag (full-fidelity).
+    incremental: true,
   }
   // md routes piggyback on the same emit sites (task 2.8): templates land in
   // the SAME jinja dir, the frozen manifest next to it in `.brust/` (the dist

package/runtime/cli/native-routes-emit.ts

@@ -1,3 +1,4 @@
+import { createHash } from 'node:crypto'
 import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
 import { createRequire } from 'node:module'
 import { dirname, relative, resolve } from 'node:path'
@@ -290,6 +291,89 @@ export interface NativeRouteEmitOpts {
   /** Repo root. Retained for call-site compatibility; native compilation now
    * goes through the napi addon's `compileJsx`, not a target/ binary. */
   repoRoot: string
+  /** Dev-loop incremental compile (R14). When true, each route's resolved
+   * compileJsx inputs (route source + every transitively imported local source
+   * + the lucide/directive/component-source env) are content-hashed and memoized
+   * for the lifetime of the process; an unchanged route SKIPS compileJsx and the
+   * sidecar rewrites (the previous emit's outputs are already on disk) but still
+   * appears in the returned manifest. ANY error in hashing falls back to a full
+   * compile — correctness over speed. Set only by `brust dev`'s emit calls;
+   * `brust build` stays full-fidelity (default false → no memo read OR write,
+   * and any stale memo entry for the route is dropped). */
+  incremental?: boolean
+  /** TEST SEAM — replaces the canonical-input hasher so tests can prove the
+   * hash-failure → compile-all fallback. Never set outside tests. */
+  hashInputsForTest?: (canonicalInputs: string) => string
+}
+
+/** Per-route emit outcome counts for `emitNativeTemplates` — testability seam
+ * for the dev-loop incremental memo (R14). `compiled + skipped` = routes
+ * emitted (routes dropped for a missing import count in neither). */
+export interface NativeEmitStats {
+  compiled: number
+  skipped: number
+}
+
+/** Dev-session memo for the incremental path: `outDir\0templateName` →
+ * { hash of the resolved compileJsx inputs, output files written by the last
+ * compile }. In-memory only (per dev process, by design — no persistence). */
+const nativeEmitMemo = new Map<string, { hash: string; outputs: string[] }>()
+
+/** Clear the incremental memo (test isolation). */
+export function resetNativeEmitMemo(): void {
+  nativeEmitMemo.clear()
+}
+
+/** Key-sorted shallow copy so JSON.stringify is order-independent (gather order
+ * is deterministic per content, but sorting makes the hash robust to it). */
+function sortRecord(rec: Record<string, string>): Record<string, string> {
+  return Object.fromEntries(Object.entries(rec).sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0)))
+}
+
+/** Canonicalize EVERYTHING that feeds a route's compile + post-processing:
+ * the exact compileJsx arguments (route source/path, transitive component
+ * sources, lucide icons, directive names), the resolved import refs (they shape
+ * the .islands.json/.components.json/.factory.ts sidecars), and the per-emit
+ * env that mutates the template after compile (directive force-bake, generator
+ * meta, dev-client splice). If it can change the bytes on disk, it is in here. */
+function canonicalCompileInputs(input: {
+  routeSource: string
+  routeSourcePath: string
+  sources: Record<string, string>
+  lucideIcons: Record<string, string>
+  directiveNames: Record<string, string>
+  mergedImports: Map<string, ResolvedImport>
+  hasDirectives: boolean
+  generatorMeta: string
+  devClient: boolean
+}): string {
+  return JSON.stringify({
+    routeSource: input.routeSource,
+    routeSourcePath: input.routeSourcePath,
+    sources: sortRecord(input.sources),
+    lucideIcons: sortRecord(input.lucideIcons),
+    directiveNames: sortRecord(input.directiveNames),
+    imports: [...input.mergedImports.entries()]
+      .map(
+        ([ident, ref]) =>
+          [ident, ref.spec, ref.bare, ref.kind, ref.imported ?? ''] as [
+            string,
+            string,
+            boolean,
+            string,
+            string,
+          ],
+      )
+      .sort((a, b) => (a[0] < b[0] ? -1 : a[0] > b[0] ? 1 : 0)),
+    hasDirectives: input.hasDirectives,
+    generatorMeta: input.generatorMeta,
+    devClient: input.devClient,
+  })
+}
+
+/** Default canonical-input hasher (overridable per-call via the test seam). */
+function sha256Hex(canonicalInputs: string): string {
+  return createHash('sha256').update(canonicalInputs).digest('hex')
 }
 
 /** Raw component entry from compileJsx's `componentsJson` field. camelCase keys
@@ -478,7 +562,7 @@ export function emitComponentArtifacts(
   return { islandIdsFromComponents }
 }
 
-export async function emitNativeTemplates(opts: NativeRouteEmitOpts): Promise<void> {
+export async function emitNativeTemplates(opts: NativeRouteEmitOpts): Promise<NativeEmitStats> {
   mkdirSync(opts.outDir, { recursive: true })
 
   // md-route exclusion lives HERE (not at the call sites): a chain whose LEAF
@@ -535,6 +619,7 @@ export async function emitNativeTemplates(opts: NativeRouteEmitOpts): Promise<vo
   const generatorMeta = resolveGenerator(opts.outDir).meta
 
   const built: string[] = []
+  const stats: NativeEmitStats = { compiled: 0, skipped: 0 }
   for (const r of nativeRoutes) {
     const name = r.nativeTemplate!
     const sourcePath = importMap.get(name)
@@ -612,6 +697,44 @@ export async function emitNativeTemplates(opts: NativeRouteEmitOpts): Promise<vo
       }
     }
 
+    // R14 — dev incremental memo. EVERYTHING hashed here is the resolved input
+    // set: the gather steps above re-read every transitive local source fresh on
+    // each emit, so an edit anywhere in the route's import graph changes
+    // `sources` (or lucide/directive env) and misses the memo. ANY hashing error
+    // → undefined → compile (correctness over speed). Non-incremental calls
+    // (brust build, boot staleness) never read the memo and DROP the route's
+    // entry below, so a later incremental emit can't trust outputs it didn't
+    // verify against this exact hash.
+    const memoKey = `${opts.outDir}\0${name}`
+    let inputsHash: string | undefined
+    if (opts.incremental) {
+      try {
+        inputsHash = (opts.hashInputsForTest ?? sha256Hex)(
+          canonicalCompileInputs({
+            routeSource,
+            routeSourcePath,
+            sources,
+            lucideIcons,
+            directiveNames,
+            mergedImports,
+            hasDirectives,
+            generatorMeta,
+            devClient: process.env.BRUST_DEV === '1',
+          }),
+        )
+      } catch {
+        inputsHash = undefined
+      }
+      const prev = inputsHash !== undefined ? nativeEmitMemo.get(memoKey) : undefined
+      if (prev && prev.hash === inputsHash && prev.outputs.every((p) => existsSync(p))) {
+        // Unchanged route: the previous emit's .jinja + sidecars are on disk —
+        // skip compileJsx and every rewrite, but still report the template.
+        built.push(name)
+        stats.skipped++
+        continue
+      }
+    }
+
     let compiled: { template: string; islandsJson: string; warnings?: string[] }
     try {
       compiled = compileJsx!(routeSource, routeSourcePath, sources, lucideIcons, directiveNames)
@@ -644,6 +767,8 @@ export async function emitNativeTemplates(opts: NativeRouteEmitOpts): Promise<vo
       process.env.BRUST_DEV === '1' ? injectDevClientIntoTemplate(withGenerator) : withGenerator
     writeFileSync(outPath, template)
     built.push(name)
+    stats.compiled++
+    const outputs = [outPath]
 
     // Islands post-processing. The compiler reports an island manifest ONLY
     // when the route uses <Island>; `"[]"` ⇒ no islands ⇒ leave the .jinja
@@ -653,6 +778,7 @@ export async function emitNativeTemplates(opts: NativeRouteEmitOpts): Promise<vo
     if (compiled.islandsJson && compiled.islandsJson !== '[]') {
       writeFileSync(islandsJsonPath, compiled.islandsJson)
       reconcileIslandManifest(outPath, islandsJsonPath, mergedImports, name)
+      outputs.push(islandsJsonPath)
     } else if (existsSync(islandsJsonPath)) {
       rmSync(islandsJsonPath, { force: true })
     }
@@ -661,6 +787,19 @@ export async function emitNativeTemplates(opts: NativeRouteEmitOpts): Promise<vo
     const compJsonStr = (compiled as any).componentsJson ?? '[]'
     if (compJsonStr !== '[]') {
       emitComponentArtifacts(outPath, compJsonStr, mergedImports, name)
+      outputs.push(
+        outPath.replace(/\.jinja$/, '.components.json'),
+        outPath.replace(/\.jinja$/, '.factory.ts'),
+      )
+    }
+
+    // R14 — memoize only what was hashed AND written by an incremental call;
+    // a non-incremental compile (build/boot) invalidates the entry instead
+    // (its writes weren't checked against any hash → never trust-skip them).
+    if (opts.incremental && inputsHash !== undefined) {
+      nativeEmitMemo.set(memoKey, { hash: inputsHash, outputs })
+    } else {
+      nativeEmitMemo.delete(memoKey)
     }
   }
 
@@ -668,6 +807,13 @@ export async function emitNativeTemplates(opts: NativeRouteEmitOpts): Promise<vo
     resolve(opts.outDir, '_manifest.json'),
     JSON.stringify({ templates: built, generatedAt: new Date().toISOString() }, null, 2),
   )
+
+  if (opts.incremental && nativeRoutes.length > 0) {
+    console.log(
+      `[brust] dev: native templates — ${stats.compiled} compiled, ${stats.skipped} unchanged (skipped)`,
+    )
+  }
+  return stats
 }
 
 /** A JSX SSR-component ident is always Capitalized — `<Search/>` lowers to an

package/runtime/config.ts

@@ -14,6 +14,12 @@ export interface BrustConfig {
   cacheMaxEntries?: number
   /** L2 page-cache capacity (entries). Undefined → Rust default of 1000. */
   cachePageMaxEntries?: number
+  /** R9 cross-process cache invalidation: redis/dragonfly URL. Absent →
+   * feature disabled (current single-process behavior). */
+  cacheSyncUrl?: string
+  /** Pub/sub channel for cache invalidation. Undefined → module default
+   * (`brust:cache:invalidate`). */
+  cacheSyncChannel?: string
 }
 
 /** Caller-supplied fallbacks (e.g. `brust.run({ address, port })`) applied
@@ -85,6 +91,8 @@ export async function loadConfig(
     workers,
     cacheMaxEntries: fromToml.cacheMaxEntries,
     cachePageMaxEntries: fromToml.cachePageMaxEntries,
+    cacheSyncUrl: fromEnv.cacheSyncUrl ?? fromToml.cacheSyncUrl,
+    cacheSyncChannel: fromEnv.cacheSyncChannel ?? fromToml.cacheSyncChannel,
   }
 }
 
@@ -168,6 +176,26 @@ function extractFromToml(parsed: unknown, file: string): Partial<BrustConfig> {
       }
       out.cachePageMaxEntries = pageMaxEntries
     }
+    const syncUrl = (cache as Record<string, unknown>).sync_url
+    if (syncUrl !== undefined) {
+      if (typeof syncUrl !== 'string' || syncUrl.trim() === '') {
+        throw new BrustConfigError(
+          `${file}: cache.sync_url must be a non-empty string (got ${JSON.stringify(syncUrl)})`,
+          file,
+        )
+      }
+      out.cacheSyncUrl = syncUrl.trim()
+    }
+    const syncChannel = (cache as Record<string, unknown>).sync_channel
+    if (syncChannel !== undefined) {
+      if (typeof syncChannel !== 'string' || syncChannel.trim() === '') {
+        throw new BrustConfigError(
+          `${file}: cache.sync_channel must be a non-empty string (got ${JSON.stringify(syncChannel)})`,
+          file,
+        )
+      }
+      out.cacheSyncChannel = syncChannel.trim()
+    }
   }
 
   return out
@@ -202,5 +230,19 @@ function extractFromEnv(): Partial<BrustConfig> {
     }
     out.workers = n
   }
+  if (process.env.BRUST_CACHE_SYNC_URL) {
+    const url = process.env.BRUST_CACHE_SYNC_URL.trim()
+    if (url === '') {
+      throw new BrustConfigError('BRUST_CACHE_SYNC_URL must be a non-empty string', null)
+    }
+    out.cacheSyncUrl = url
+  }
+  if (process.env.BRUST_CACHE_SYNC_CHANNEL) {
+    const channel = process.env.BRUST_CACHE_SYNC_CHANNEL.trim()
+    if (channel === '') {
+      throw new BrustConfigError('BRUST_CACHE_SYNC_CHANNEL must be a non-empty string', null)
+    }
+    out.cacheSyncChannel = channel
+  }
   return out
 }