@brust/cache-cloudflare 0.0.0-stage → 2.0.0-alpha.4

package/README.md

@@ -1,3 +1,77 @@
-# Temporary Holding Version
+# @brust/cache-cloudflare
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Cloudflare Workers adapters for brust's shared second cache tier (`[cache]` in `brust.toml`, `brust build --target cloudflare`):
+
+- **`cloudflare-kv`**: pages in Workers KV (a store, no broadcast).
+- **`cloudflare-do`**: invalidations through a Durable Object (a pull broadcast), optionally also the page store (`do_store = true`, 16 shards).
+- **`cloudflare-kv` + `broadcast = "cloudflare-do"`**: the recommended pair (`combine`). KV holds the bodies, the Durable Object tells every isolate what was invalidated.
+
+Workers only (`runtimes: ['workers']`). No `bun`/`bun:*` import. Peer dependency: `@brust/core`.
+
+```toml
+[cache]
+adapter = "cloudflare-kv"
+broadcast = "cloudflare-do"
+epoch_interval_ms = 5000
+
+[cache.cloudflare]
+kv_min_ttl_s = 300
+```
+
+## Wrangler bindings (you declare them; brust never adds them)
+
+`brust build --target cloudflare` checks the top level and every `env.*` block of your wrangler config and fails with this snippet when something is missing:
+
+```jsonc
+{
+  "kv_namespaces": [{ "binding": "BRUST_CACHE", "id": "<wrangler kv namespace create brust-cache>" }],
+  "durable_objects": { "bindings": [{ "name": "BRUST_CACHE_DO", "class_name": "BrustCacheDO" }] },
+  "migrations": [{ "tag": "brust-cache-v1", "new_sqlite_classes": ["BrustCacheDO"] }]
+}
+```
+
+`BrustCacheDO` must be a SQLite-backed class (`new_sqlite_classes`, or `exports.BrustCacheDO = { "type": "durable-object", "storage": "sqlite" }`). `brust build` writes `dist/cf/worker/main.js`, which re-exports it; do not write your own.
+
+## Options (`[cache.cloudflare]`)
+
+| key | used by | default | rule |
+|---|---|---|---|
+| `kv_binding` | KV, pair | `"BRUST_CACHE"` | a binding name in `kv_namespaces` |
+| `kv_min_ttl_s` | KV, pair | `300` | `0..=31536000`; a route with a smaller ttl is not written to KV (KV's own floor is 60 s) |
+| `do_binding` | DO, pair | `"BRUST_CACHE_DO"` | a `durable_objects` binding with `class_name "BrustCacheDO"` |
+| `do_store` | DO | `false` | `true` = bodies in 16 Durable Object shards (ignored with the pair) |
+
+Programmatic forms (for `adapter = "custom"`): `kvAdapter({ binding?, min_ttl_s? })`, `doAdapter({ binding?, store? })`, `combine(kv, do)`. An unknown key is a `TypeError` naming it.
+
+## What each configuration guarantees
+
+| config | store | other isolates after `cache.invalidate` | stale body re-served? | Free-plan cost driver |
+|---|---|---|---|---|
+| `cloudflare-kv` alone | KV, unguarded | up to the ttl (no broadcast) | **yes**, up to the ttl (at least 300 s) | 1 KV write per MISS |
+| `cloudflare-do`, `do_store = false` | none (tier 1 only) | `epoch_interval_ms` + RTT | no | 1 DO request per poll per isolate |
+| `cloudflare-do`, `do_store = true` | DO shards, exact write guard | `epoch_interval_ms` + RTT | no (rows are deleted) | + 1 DO request per tier-1 miss, + 18 per invalidation |
+| `cloudflare-kv` + `broadcast = "cloudflare-do"` | KV, floor-guarded | `epoch_interval_ms` + RTT | no once the floor is known; KV lag is hidden by each entry's `entryStamp` | KV write per MISS + DO polls |
+
+**KV alone never invalidates.** An L2 key hashes prefix, method, path and query, so a tag or a path cannot be enumerated in KV without extra index writes. Pair it with the Durable Object broadcast unless a stale page for up to its ttl is fine.
+
+With the pair, each isolate keeps invalidation floors in JS (seeded from the Durable Object on first contact and after a generation change), so a freshly started isolate never serves a KV body that was invalidated before it started.
+
+## Free-plan numbers
+
+| driver | per day | Free quota | note |
+|---|---|---|---|
+| epoch polls, 1 busy isolate, `epoch_interval_ms` 1000 | 86,400 DO requests | 100,000 DO requests | 86 % for ONE isolate |
+| same at 5000 ms | 17,280 | 100,000 | about 5 busy isolates |
+| same at 60000 ms | 1,440 | 100,000 | about 69 isolates; staleness about 60 s |
+| `do_store` tier-1 miss | 1 DO request each | 100,000 | plus rows read |
+| invalidation | 1 DO request (18 with `do_store`) + at most 5 rows written | 100,000 rows written | |
+| KV write-through | 1 KV write per MISS of a ttl >= 300 s page | 1,000 writes | the binding constraint on Free |
+| KV read-through | 1 KV read per tier-1 miss | 100,000 reads | |
+
+On Free, set `epoch_interval_ms >= 5000` and prefer KV + DO over `do_store`. A `do_store` invalidation issues about 18 subrequests inside the action's invocation (Free allows 50); an action that already makes more than 30 will see shard invalidations fail.
+
+## Behaviour notes
+
+- The Durable Object persists its `seq` and the name-to-seq floors in its SQLite storage, so seqs never regress across a restart. The event ring is in memory and `gen` is new on every construction, so every isolate clears tier 1 once after a restart.
+- A KV write is skipped when this isolate wrote an identical page less than 60 s ago (KV allows one write per second per key).
+- KV is eventually consistent (up to about 60 s across locations). Local `wrangler dev` KV is strongly consistent, so propagation lag is not covered by the test suite.

package/package.json

@@ -1,6 +1,35 @@
 {
   "name": "@brust/cache-cloudflare",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "2.0.0-alpha.4",
+  "description": "brust cache adapters for Cloudflare Workers: KV store, Durable Object broadcast/store, and their combination",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/AssetsArt/brust.git"
+  },
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts",
+    "./kv": "./src/kv.ts",
+    "./do": "./src/do.ts"
+  },
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "scripts": {
+    "test": "bun test",
+    "typecheck": "bun check"
+  },
+  "peerDependencies": {
+    "@brust/core": "2.0.0-alpha.4"
+  },
+  "devDependencies": {
+    "@brust/core": "2.0.0-alpha.4",
+    "@types/bun": "^1.4.0",
+    "typescript": "^7.0.2"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/cloudflare.d.ts

@@ -0,0 +1,34 @@
+// The Cloudflare subset this package uses, declared ambiently: @cloudflare/workers-types' global Request/Response clash with
+// lib DOM under `bun check` (same precedent as examples/pokedex/lib/cloudflare.d.ts).
+interface KVNamespaceGetOptions { type?: 'text' | 'arrayBuffer'; cacheTtl?: number }
+interface KVNamespace {
+  get(key: string, options: { type: 'arrayBuffer'; cacheTtl?: number }): Promise<ArrayBuffer | null>
+  put(key: string, value: ArrayBuffer | ArrayBufferView | string, options?: { expirationTtl?: number }): Promise<void>
+  delete(key: string): Promise<void>
+}
+interface SqlStorageCursor<T> extends Iterable<T> {
+  toArray(): T[]
+  one(): T
+  readonly rowsWritten: number
+}
+interface SqlStorage {
+  exec<T = Record<string, unknown>>(query: string, ...bindings: unknown[]): SqlStorageCursor<T>
+}
+interface DurableObjectStorage {
+  sql: SqlStorage
+  transactionSync<T>(fn: () => T): T
+  setAlarm(time: number): Promise<void>
+  getAlarm(): Promise<number | null>
+}
+interface DurableObjectState {
+  storage: DurableObjectStorage
+  blockConcurrencyWhile<T>(fn: () => Promise<T>): Promise<T>
+}
+declare module 'cloudflare:workers' {
+  export const env: Record<string, unknown>
+  export class DurableObject<E = Record<string, unknown>> {
+    constructor(ctx: DurableObjectState, env: E)
+    protected ctx: DurableObjectState
+    protected env: E
+  }
+}

package/src/combine.ts

@@ -0,0 +1,84 @@
+// combine(kv, do): the KV store + the DO broadcast, with correct invalidation floors kept in JS (R6). The Rust cursor alone is not enough: an isolate that
+// first-contacts the DO adopts without replay, so it would serve a KV body invalidated before it started, for up to ttl. Floors are seeded from the DO
+// (persisted names -> seq), raised by every replayed event / own publish / local invalidate, and judge each KV hit by its `entryStamp`.
+import type { CacheAdapter, CacheStore, GetResult, InvalidateArgs, SetMeta, StoredPage } from '@brust/core/cache-adapter'
+import type { DoAdapter } from './do-adapter'
+import { Floors } from './floors'
+import type { KvAdapter } from './kv-adapter'
+
+export function combine(kvIn: CacheAdapter, d: DoAdapter): CacheAdapter {
+  const kv = kvIn as KvAdapter
+  if (!kv.store || typeof kv.store.getWithMeta !== 'function')
+    throw new TypeError(`cloudflare-do broadcast can only be composed with the "cloudflare-kv" store (got "${kvIn.name}")`)
+  const floors = new Floors()
+  let gen: string | null = null
+  let lastSeq = 0
+  let seeded = false
+  let seeding: Promise<void> | null = null
+  const seed = () =>
+    (seeding ??= (async () => {
+      try {
+        const f = await d.floors()
+        floors.seed({ names: f.names, evicted: f.evicted })
+        gen = f.gen
+        lastSeq = Math.max(lastSeq, f.seq)
+        seeded = true
+      } finally {
+        seeding = null
+      }
+    })())
+
+  const store: CacheStore = {
+    maxBodyBytes: kv.store.maxBodyBytes,
+    async get(key): Promise<GetResult> {
+      if (!seeded) await seed()
+      const stamp = lastSeq
+      const { result, meta } = await kv.store.getWithMeta(key)
+      if (!result.page || !meta) return { page: null, stamp, entryStamp: null, storedAt: null }
+      // A hit written under a stamp below its floor (or one with no stamp at all) is judged invalid.
+      if (result.entryStamp === null || result.entryStamp < floors.floorOf(meta.tags, meta.method, meta.path)) return { page: null, stamp, entryStamp: null, storedAt: null }
+      return { ...result, stamp }
+    },
+    async set(key: string, page: StoredPage, meta: SetMeta) {
+      if (!seeded) await seed()
+      // `stamp: null` = an unguarded write: it is stamped with the seq known now, so floors judge it from here on.
+      const stamp = meta.stamp ?? lastSeq
+      if (meta.stamp !== null && stamp < floors.floorOf(meta.tags, meta.method, meta.path)) return false
+      return kv.store.set(key, page, { ...meta, stamp })
+    },
+    async invalidate(args: InvalidateArgs) {
+      // Hide the pages at once on this isolate; the matching publish returns the real seq (>= lastSeq + 1) and raises it.
+      floors.raiseArgs(args, lastSeq + 1)
+    },
+  }
+
+  return {
+    name: 'cloudflare-kv+do',
+    runtimes: ['workers'],
+    store,
+    broadcast: {
+      async publish(args, origin) {
+        const seq = await d.broadcast.publish(args, origin)
+        floors.raiseArgs(args, seq)
+        lastSeq = Math.max(lastSeq, seq)
+        return seq
+      },
+      async since(seq) {
+        const r = await d.broadcast.since(seq)
+        if (!seeded || r.gen !== gen || r.behind) await seed()
+        else {
+          for (const e of r.events) floors.raiseArgs(e.args, e.seq)
+          lastSeq = Math.max(lastSeq, r.seq)
+        }
+        return r
+      },
+    },
+    async init(ctx) {
+      await kv.init?.(ctx)
+      await d.init?.(ctx)
+    },
+    async close() {
+      await Promise.allSettled([kv.close?.(), d.close?.()])
+    },
+  }
+}

package/src/do-adapter.ts

@@ -0,0 +1,146 @@
+// The Durable Object adapter: a pull BROADCAST (one `epoch:<ns>` instance) and, with `store: true`, an exact-guarded body store over 16 shards.
+// No class import here (it needs `cloudflare:workers` at load): `do.ts` re-exports BrustCacheDO beside this.
+import type { CacheAdapter, CacheAdapterFactory, CacheBroadcast, CacheStore, EpochSince, GetResult, InvalidateArgs, SetMeta, StoredPage } from '@brust/core/cache-adapter'
+import { combine } from './combine'
+import { binding, type GetEnv, workersEnv } from './env'
+import { decodeEntry, encodeEntry } from './frame'
+import type { FloorsPayload, PageMeta } from './do-class'
+import { type DoOptions, fromTable, parseDo } from './options'
+
+export const SHARDS = 16
+/** A DO SQLite row is capped at 2 MB; the frame (headers + meta) shares it. */
+export const MAX_DO_BODY_BYTES = 1_900_000
+
+/** The RPC surface of a BrustCacheDO stub (types only: do-class.ts is not imported at runtime). */
+export interface EpochStub {
+  head(): Promise<{ gen: string; seq: number }>
+  since(seq: number): Promise<EpochSince>
+  publish(args: InvalidateArgs, origin: string): Promise<{ gen: string; seq: number }>
+  floors(): Promise<FloorsPayload>
+}
+export interface ShardStub {
+  get(key: string): Promise<Uint8Array | null>
+  set(key: string, frame: Uint8Array, meta: PageMeta, stamp: number | null): Promise<boolean>
+  invalidate(args: InvalidateArgs, seq: number): Promise<number>
+}
+interface Namespace { getByName(name: string): unknown }
+
+export interface DoDeps { getEnv?: GetEnv; now?: () => number; retryMs?: number }
+export interface DoAdapter extends CacheAdapter {
+  broadcast: CacheBroadcast & { since(seq: number): Promise<EpochSince> }
+  /** The persisted floors + seq + gen of the epoch instance (combine seeds from it). */
+  floors(): Promise<FloorsPayload>
+  /** The lane-A composer hook: `[cache] adapter = "cloudflare-kv"` + `broadcast = "cloudflare-do"` is exactly `combine`. */
+  composeWith(store: CacheAdapter): CacheAdapter
+}
+
+export function shardIndex(key: string): number {
+  const n = Number.parseInt(key.at(-1) ?? '', 16)
+  if (!Number.isNaN(n)) return n
+  let h = 0x811c9dc5
+  for (let i = 0; i < key.length; i++) h = Math.imul(h ^ key.charCodeAt(i), 0x01000193) >>> 0
+  return h % SHARDS
+}
+
+export function doAdapter(options: DoOptions = {}, deps: DoDeps = {}): DoAdapter {
+  const { binding: name, store: withStore } = parseDo(options)
+  const getEnv = deps.getEnv ?? workersEnv
+  const now = deps.now ?? Date.now
+  const retryMs = deps.retryMs ?? 250
+  let namespace = 'brust'
+  let lastSeq: number | null = null
+  const seen = (s: number) => {
+    lastSeq = Math.max(lastSeq ?? 0, s)
+  }
+  const ns = async () => binding<Namespace>(await getEnv(), name, 'Durable Object')
+  const epoch = async () => (await ns()).getByName(`epoch:${namespace}`) as EpochStub
+  const shard = async (i: number) => (await ns()).getByName(`store:${namespace}:${i}`) as ShardStub
+
+  // Lane A calls store.invalidate FIRST (delete, then publish: L7a), so the store side cannot publish (it does not know the runtime's origin).
+  // It writes its shard markers at the seq the publish is about to take (head + 1, L7b), and remembers that; publish then only re-marks when the
+  // real seq turned out different. Exactly ONE epoch publish happens per invalidation.
+  const pending = new WeakMap<object, number>()
+  const fanout = async (args: InvalidateArgs, seq: number): Promise<Error | null> => {
+    const out = await Promise.allSettled(Array.from({ length: SHARDS }, async (_, i) => (await shard(i)).invalidate(args, seq)))
+    const bad = out.filter((o) => o.status === 'rejected').length
+    return bad > 0 ? new Error(`cloudflare-do: ${bad}/${SHARDS} shard invalidations failed`) : null
+  }
+
+  const broadcast: DoAdapter['broadcast'] = {
+    async publish(args, origin) {
+      const ep = await epoch()
+      let res: { gen: string; seq: number }
+      try {
+        res = await ep.publish(args, origin)
+      } catch {
+        await new Promise((r) => setTimeout(r, retryMs))
+        res = await ep.publish(args, origin)
+      }
+      seen(res.seq)
+      if (withStore && pending.get(args) !== res.seq) {
+        const err = await fanout(args, res.seq)
+        if (err) console.error(`[brust] ${err.message}`)
+      }
+      return res.seq
+    },
+    async since(seq) {
+      const r = await (await epoch()).since(seq)
+      seen(r.seq)
+      return r
+    },
+  }
+
+  let store: CacheStore | undefined
+  if (withStore) {
+    const ensureSeq = async () => {
+      if (lastSeq === null) seen((await (await epoch()).head()).seq)
+    }
+    store = {
+      maxBodyBytes: MAX_DO_BODY_BYTES,
+      async get(key): Promise<GetResult> {
+        await ensureSeq()
+        const stamp = lastSeq
+        const raw = await (await shard(shardIndex(key))).get(key)
+        const e = raw ? decodeEntry(raw) : null
+        if (!e) return { page: null, stamp, entryStamp: null, storedAt: null }
+        return { page: e.page, stamp, entryStamp: e.meta.entryStamp, storedAt: e.meta.storedAt }
+      },
+      async set(key: string, page: StoredPage, meta: SetMeta) {
+        if (page.body.length > MAX_DO_BODY_BYTES) return false
+        const at = now()
+        const expiresAt = at + meta.ttlMs
+        const frame = encodeEntry(page, { tags: meta.tags, method: meta.method, path: meta.path, entryStamp: meta.stamp, storedAt: at, expiresAt })
+        return (await shard(shardIndex(key))).set(key, frame, { tags: meta.tags, method: meta.method, path: meta.path, expiresAt }, meta.stamp)
+      },
+      async invalidate(args: InvalidateArgs) {
+        const head = await (await epoch()).head()
+        seen(head.seq)
+        pending.set(args, head.seq + 1)
+        const err = await fanout(args, head.seq + 1)
+        if (err) throw err
+      },
+    }
+  }
+
+  const adapter: DoAdapter = {
+    name: 'cloudflare-do',
+    runtimes: ['workers'],
+    ...(store ? { store } : {}),
+    broadcast,
+    async init(ctx) {
+      namespace = ctx.namespace
+    },
+    async floors() {
+      const f = await (await epoch()).floors()
+      seen(f.seq)
+      return f
+    },
+    composeWith(base) {
+      return combine(base, adapter)
+    },
+  }
+  return adapter
+}
+
+/** The `[cache.cloudflare]` table (`do_binding`, `do_store`) -> the adapter (the default export of `/do`). */
+export const doFactory: CacheAdapterFactory = (table) => doAdapter(fromTable(table, 'cloudflare-do').do)

package/src/do-class.ts

@@ -0,0 +1,165 @@
+// BrustCacheDO: ONE class for both roles. The instance named `epoch:<ns>` is the broadcast (ring + persisted seq and floors); instances named
+// `store:<ns>:<0..f>` are body shards (exact write guard). SQLite-backed (migrations `new_sqlite_classes`). seq and the name -> seq floors
+// persist (R7) so seqs never regress across a restart; the ring stays in memory and `gen` is new on every construction, so isolates clear once.
+import { DurableObject } from 'cloudflare:workers'
+import type { EpochSince, InvalidateArgs } from '@brust/core/cache-adapter'
+import { namesOf, pathName } from './floors'
+import { Ring } from './ring'
+
+export const INVAL_CAP = 4096
+const SWEEP_MS = 60_000
+
+export interface PageMeta { tags: string[]; method: string; path: string; expiresAt: number }
+export interface FloorsPayload { gen: string; seq: number; names: [string, number][]; evicted: number }
+
+export class BrustCacheDO extends DurableObject {
+  private sql: SqlStorage
+  private gen = crypto.randomUUID()
+  private ring = new Ring(this.gen, 0)
+  private evicted = 0
+  private invalCount = 0
+  private publishes = 0
+  private failNext = false
+
+  constructor(ctx: DurableObjectState, env: Record<string, unknown>) {
+    super(ctx, env)
+    this.sql = ctx.storage.sql
+    void ctx.blockConcurrencyWhile(async () => {
+      const sql = this.sql
+      sql.exec('CREATE TABLE IF NOT EXISTS meta(k TEXT PRIMARY KEY, v INTEGER)')
+      sql.exec('CREATE TABLE IF NOT EXISTS inval(name TEXT PRIMARY KEY, seq INTEGER NOT NULL)')
+      sql.exec('CREATE INDEX IF NOT EXISTS inval_seq ON inval(seq)')
+      sql.exec('CREATE TABLE IF NOT EXISTS pages(key TEXT PRIMARY KEY, meta TEXT NOT NULL, body BLOB NOT NULL, mpath TEXT NOT NULL, expires_at INTEGER NOT NULL)')
+      sql.exec('CREATE TABLE IF NOT EXISTS tags(tag TEXT NOT NULL, key TEXT NOT NULL, PRIMARY KEY(tag, key))')
+      const m = (k: string) => (sql.exec<{ v: number }>('SELECT v FROM meta WHERE k = ?', k).toArray()[0]?.v ?? 0)
+      this.evicted = m('evicted')
+      this.invalCount = sql.exec<{ c: number }>('SELECT count(*) AS c FROM inval').one().c
+      this.ring = new Ring(this.gen, m('seq'))
+    })
+  }
+
+  private testOnly(): void {
+    if ((this.env as Record<string, unknown>).BRUST_CACHE_TEST !== '1') throw new Error('BrustCacheDO: test hooks are disabled')
+  }
+  private maybeFail(): void {
+    if (this.failNext) {
+      this.failNext = false
+      throw new Error('BrustCacheDO: injected failure')
+    }
+  }
+  private setMeta(k: string, v: number): void {
+    this.sql.exec('INSERT INTO meta(k, v) VALUES(?, ?) ON CONFLICT(k) DO UPDATE SET v = excluded.v', k, v)
+  }
+
+  /** Raise the floors of `names` to at least `seq`; keep at most INVAL_CAP rows, raising `evicted` by what is dropped. */
+  private bump(names: string[], seq: number): void {
+    for (const n of names) {
+      if (this.sql.exec('SELECT 1 FROM inval WHERE name = ?', n).toArray().length === 0) this.invalCount += 1
+      this.sql.exec('INSERT INTO inval(name, seq) VALUES(?, ?) ON CONFLICT(name) DO UPDATE SET seq = max(seq, excluded.seq)', n, seq)
+    }
+    const over = this.invalCount - INVAL_CAP
+    if (over > 0) {
+      const old = this.sql.exec<{ name: string; seq: number }>('SELECT name, seq FROM inval ORDER BY seq ASC LIMIT ?', over).toArray()
+      for (const o of old) {
+        this.sql.exec('DELETE FROM inval WHERE name = ?', o.name)
+        this.evicted = Math.max(this.evicted, o.seq)
+      }
+      this.invalCount -= old.length
+      this.setMeta('evicted', this.evicted)
+    }
+  }
+
+  // ---- epoch role ----
+  head(): { gen: string; seq: number } {
+    return { gen: this.gen, seq: this.ring.seq }
+  }
+  since(seq: number): EpochSince {
+    this.maybeFail()
+    return this.ring.since(seq)
+  }
+  publish(args: InvalidateArgs, origin: string): { gen: string; seq: number } {
+    this.maybeFail()
+    this.publishes += 1
+    return this.ctx.storage.transactionSync(() => {
+      const seq = this.ring.publish(args, origin)
+      this.setMeta('seq', seq)
+      this.bump(namesOf(args), seq)
+      return { gen: this.gen, seq }
+    })
+  }
+  floors(): FloorsPayload {
+    const rows = this.sql.exec<{ name: string; seq: number }>('SELECT name, seq FROM inval ORDER BY seq DESC LIMIT ?', INVAL_CAP).toArray()
+    return { gen: this.gen, seq: this.ring.seq, names: rows.map((r) => [r.name, r.seq]), evicted: this.evicted }
+  }
+
+  // ---- shard role ----
+  get(key: string): Uint8Array | null {
+    const row = this.sql.exec<{ body: ArrayBuffer; expires_at: number }>('SELECT body, expires_at FROM pages WHERE key = ?', key).toArray()[0]
+    if (!row) return null
+    if (row.expires_at <= Date.now()) {
+      this.dropKeys([key])
+      return null
+    }
+    return new Uint8Array(row.body)
+  }
+  /** `stamp === null` = an unguarded write (the same rule as every store); otherwise refused when an invalidation of its names is newer. */
+  async set(key: string, frame: Uint8Array, meta: PageMeta, stamp: number | null): Promise<boolean> {
+    const ok = this.ctx.storage.transactionSync(() => {
+      if (stamp !== null) {
+        if (this.evicted > stamp) return false
+        for (const n of [...meta.tags.map((t) => `t:${t}`), pathName(meta.method, meta.path)]) {
+          const r = this.sql.exec<{ seq: number }>('SELECT seq FROM inval WHERE name = ?', n).toArray()[0]
+          if (r && r.seq > stamp) return false
+        }
+      }
+      this.dropKeys([key])
+      this.sql.exec('INSERT INTO pages(key, meta, body, mpath, expires_at) VALUES(?, ?, ?, ?, ?)', key, JSON.stringify({ tags: meta.tags, method: meta.method, path: meta.path }), frame, pathName(meta.method, meta.path), meta.expiresAt)
+      for (const t of new Set(meta.tags)) this.sql.exec('INSERT OR IGNORE INTO tags(tag, key) VALUES(?, ?)', t, key)
+      return true
+    })
+    if (ok && (await this.ctx.storage.getAlarm()) === null) await this.ctx.storage.setAlarm(Date.now() + SWEEP_MS)
+    return ok
+  }
+  invalidate(args: InvalidateArgs, seq: number): number {
+    return this.ctx.storage.transactionSync(() => {
+      this.bump(namesOf(args), seq)
+      const keys = new Set<string>()
+      for (const t of args.tags ?? []) for (const r of this.sql.exec<{ key: string }>('SELECT key FROM tags WHERE tag = ?', t)) keys.add(r.key)
+      if (args.path !== undefined) for (const r of this.sql.exec<{ key: string }>('SELECT key FROM pages WHERE mpath = ?', pathName(args.method, args.path))) keys.add(r.key)
+      this.dropKeys([...keys])
+      return keys.size
+    })
+  }
+  private dropKeys(keys: string[]): void {
+    for (const k of keys) {
+      this.sql.exec('DELETE FROM pages WHERE key = ?', k)
+      this.sql.exec('DELETE FROM tags WHERE key = ?', k)
+    }
+  }
+  async alarm(): Promise<void> {
+    const dead = this.sql.exec<{ key: string }>('SELECT key FROM pages WHERE expires_at <= ?', Date.now()).toArray()
+    this.dropKeys(dead.map((r) => r.key))
+    if (this.sql.exec('SELECT 1 FROM pages LIMIT 1').toArray().length > 0) await this.ctx.storage.setAlarm(Date.now() + SWEEP_MS)
+  }
+
+  // ---- test hooks (R12): only when env.BRUST_CACHE_TEST === "1" ----
+  __regen(): { gen: string; seq: number } {
+    this.testOnly()
+    this.gen = crypto.randomUUID()
+    this.ring = new Ring(this.gen, this.ring.seq)
+    return { gen: this.gen, seq: this.ring.seq }
+  }
+  __failNext(): void {
+    this.testOnly()
+    this.failNext = true
+  }
+  async __sweep(): Promise<void> {
+    this.testOnly()
+    await this.alarm()
+  }
+  __state(): { publishes: number; seq: number; gen: string; pages: number; inval: number; evicted: number } {
+    this.testOnly()
+    const pages = this.sql.exec<{ c: number }>('SELECT count(*) AS c FROM pages').one().c
+    return { publishes: this.publishes, seq: this.ring.seq, gen: this.gen, pages, inval: this.invalCount, evicted: this.evicted }
+  }
+}

package/src/do.ts

@@ -0,0 +1,3 @@
+export { BrustCacheDO } from './do-class'
+export { type DoAdapter, doAdapter, doFactory as default } from './do-adapter'
+export type { DoOptions } from './options'

package/src/env.ts

@@ -0,0 +1,14 @@
+// The Worker env, read per call: a Worker may not touch bindings at module scope, and the bundle's smoke import runs with env = {}.
+export type GetEnv = () => Promise<Record<string, unknown>>
+export const workersEnv: GetEnv = async () => (await import('cloudflare:workers')).env
+
+export function binding<T>(env: Record<string, unknown>, name: string, what: string): T {
+  const b = env[name]
+  if (b === undefined || b === null) throw new Error(`${what} binding "${name}" is not bound (add it to wrangler.jsonc)`)
+  return b as T
+}
+
+/** Only the listed keys; anything else is a TypeError naming it (it surfaces at the build smoke). */
+export function onlyKeys(o: Record<string, unknown>, allowed: readonly string[], ignored: readonly string[], what: string): void {
+  for (const k of Object.keys(o)) if (!allowed.includes(k) && !ignored.includes(k)) throw new TypeError(`${what}: unknown option "${k}" (known: ${allowed.join(', ')})`)
+}

package/src/floors.ts

@@ -0,0 +1,41 @@
+// Per-name invalidation floors (names `t:<tag>` and `p:<METHOD> <path>`): an entry written under a stamp below its floor is invalid.
+import type { InvalidateArgs } from '@brust/core/cache-adapter'
+
+export const pathName = (method: string | undefined, path: string) => `p:${method ?? 'GET'} ${path}`
+
+/** The floor names an invalidation touches. */
+export function namesOf(args: InvalidateArgs): string[] {
+  return [...(args.tags ?? []).map((t) => `t:${t}`), ...(args.path !== undefined ? [pathName(args.method, args.path)] : [])]
+}
+
+export interface FloorsSnapshot { names: [string, number][]; evicted: number }
+
+export class Floors {
+  private m = new Map<string, number>()
+  evicted = 0
+  constructor(private cap = 4096) {}
+  seed(s: FloorsSnapshot): void {
+    this.m.clear()
+    this.evicted = s.evicted
+    for (const [n, q] of s.names) this.raise(n, q)
+  }
+  raise(name: string, seq: number): void {
+    const next = Math.max(this.m.get(name) ?? 0, seq)
+    this.m.delete(name)
+    this.m.set(name, next)
+    while (this.m.size > this.cap) {
+      const [oldest, q] = this.m.entries().next().value as [string, number]
+      this.m.delete(oldest)
+      this.evicted = Math.max(this.evicted, q)
+    }
+  }
+  raiseArgs(args: InvalidateArgs, seq: number): void {
+    for (const n of namesOf(args)) this.raise(n, seq)
+  }
+  /** The highest floor over an entry's names; a name never seen is only as safe as `evicted`. */
+  floorOf(tags: string[], method: string, path: string): number {
+    let f = this.evicted
+    for (const n of [...tags.map((t) => `t:${t}`), pathName(method, path)]) f = Math.max(f, this.m.get(n) ?? 0)
+    return f
+  }
+}

package/src/frame.ts

@@ -0,0 +1,38 @@
+// KV / DO-row value: [u32 LE meta_len][meta JSON][body] (spec §5.1, the Redis framing). No KV metadata: headers + tags would pass its 1024-byte cliff.
+import type { StoredPage } from '@brust/core/cache-adapter'
+
+export interface EntryMeta {
+  v: 1
+  status: number
+  headers: [string, string][]
+  tags: string[]
+  method: string
+  path: string
+  entryStamp: number | null
+  storedAt: number
+  expiresAt: number
+}
+
+export function encodeEntry(page: StoredPage, meta: Omit<EntryMeta, 'v' | 'status' | 'headers'>): Uint8Array {
+  const m: EntryMeta = { v: 1, status: page.status, headers: page.headers, ...meta }
+  const head = new TextEncoder().encode(JSON.stringify(m))
+  const out = new Uint8Array(4 + head.length + page.body.length)
+  new DataView(out.buffer).setUint32(0, head.length, true)
+  out.set(head, 4)
+  out.set(page.body, 4 + head.length)
+  return out
+}
+
+export function decodeEntry(u8: Uint8Array): { page: StoredPage; meta: EntryMeta } | null {
+  if (u8.length < 4) return null
+  const n = new DataView(u8.buffer, u8.byteOffset, u8.byteLength).getUint32(0, true)
+  if (n > u8.length - 4) return null
+  let meta: EntryMeta
+  try {
+    meta = JSON.parse(new TextDecoder().decode(u8.subarray(4, 4 + n)))
+  } catch {
+    return null
+  }
+  if (!meta || meta.v !== 1 || !Array.isArray(meta.headers)) return null
+  return { page: { status: meta.status, headers: meta.headers, body: u8.slice(4 + n) }, meta }
+}

package/src/index.ts

@@ -0,0 +1,5 @@
+export { combine } from './combine'
+export { BrustCacheDO } from './do-class'
+export { type DoAdapter, doAdapter } from './do-adapter'
+export { type KvAdapter, kvAdapter } from './kv-adapter'
+export type { DoOptions, KvOptions } from './options'

package/src/kv-adapter.ts

@@ -0,0 +1,73 @@
+// Cloudflare KV as a cache STORE (no broadcast). Body and meta share one KV value (R4); KV alone never invalidates (R5): a stale body
+// lives until its ttl, so pair it with `broadcast = "cloudflare-do"` (combine) for correct invalidation.
+import type { CacheAdapter, CacheStore, GetResult, InvalidateArgs, SetMeta, StoredPage } from '@brust/core/cache-adapter'
+import { binding, type GetEnv, workersEnv } from './env'
+import { decodeEntry, encodeEntry, type EntryMeta } from './frame'
+import { type KvOptions, parseKv } from './options'
+
+/** KV's 60 s floor on `expirationTtl`, and its 1 write/s/key limit: an identical frame written < 60 s ago is not rewritten. */
+const MIN_EXPIRATION_S = 60
+const MEMO_CAP = 1024
+
+export interface KvStore extends CacheStore {
+  /** `get` plus the entry's stored meta (tags, method, path): combine needs them to judge an entry against its floors. */
+  getWithMeta(key: string): Promise<{ result: GetResult; meta: EntryMeta | null }>
+}
+export interface KvAdapter extends CacheAdapter {
+  store: KvStore
+}
+
+export interface KvDeps { getEnv?: GetEnv; now?: () => number }
+
+function fingerprint(u8: Uint8Array): string {
+  let h = 0x811c9dc5
+  for (let i = 0; i < u8.length; i++) h = Math.imul(h ^ u8[i]!, 0x01000193) >>> 0
+  return `${u8.length}:${h}`
+}
+
+export function kvAdapter(options: KvOptions = {}, deps: KvDeps = {}): KvAdapter {
+  const { binding: name, minTtlS } = parseKv(options)
+  const getEnv = deps.getEnv ?? workersEnv
+  const now = deps.now ?? Date.now
+  const memo = new Map<string, { at: number; fp: string }>()
+  const kv = async () => binding<KVNamespace>(await getEnv(), name, 'KV')
+
+  const store: KvStore = {
+    // The key is a 512-byte limit away from lane A's L2Key; bodies are bounded by the core's max_body_bytes (KV allows 25 MiB).
+    maxBodyBytes: 8 * 1024 * 1024,
+    async getWithMeta(key) {
+      const none = { result: { page: null, stamp: null, entryStamp: null, storedAt: null } as GetResult, meta: null }
+      const raw = await (await kv()).get(key, { type: 'arrayBuffer', cacheTtl: 60 })
+      if (!raw) return none
+      const e = decodeEntry(new Uint8Array(raw))
+      if (!e || e.meta.expiresAt <= now()) return none
+      return { result: { page: e.page, stamp: null, entryStamp: e.meta.entryStamp, storedAt: e.meta.storedAt }, meta: e.meta }
+    },
+    async get(key) {
+      return (await store.getWithMeta(key)).result
+    },
+    async set(key: string, page: StoredPage, meta: SetMeta) {
+      if (meta.ttlMs < minTtlS * 1000) return false
+      if (page.body.length > store.maxBodyBytes) return false
+      const at = now()
+      const frame = encodeEntry(page, { tags: meta.tags, method: meta.method, path: meta.path, entryStamp: meta.stamp, storedAt: at, expiresAt: at + meta.ttlMs })
+      const fp = `${fingerprint(page.body)}:${JSON.stringify([page.status, page.headers, meta.tags, meta.method, meta.path, meta.stamp])}`
+      const prev = memo.get(key)
+      if (prev && prev.fp === fp && at - prev.at < 60_000) return true
+      try {
+        await (await kv()).put(key, frame, { expirationTtl: Math.max(MIN_EXPIRATION_S, Math.ceil(meta.ttlMs / 1000)) })
+      } catch (e) {
+        if (/\b429\b|too many requests|rate limit/i.test(String((e as Error)?.message ?? e))) return false
+        throw e
+      }
+      memo.delete(key)
+      memo.set(key, { at, fp })
+      if (memo.size > MEMO_CAP) memo.delete(memo.keys().next().value as string)
+      return true
+    },
+    async invalidate(_args: InvalidateArgs) {
+      // R5: an L2Key hashes prefix+method+path+query, so a tag or path cannot be enumerated without index writes; KV alone is "stale <= ttl".
+    },
+  }
+  return { name: 'cloudflare-kv', runtimes: ['workers'], store }
+}

package/src/kv.ts

@@ -0,0 +1,10 @@
+import type { CacheAdapterFactory } from '@brust/core/cache-adapter'
+import { fromTable } from './options'
+import { type KvAdapter, kvAdapter } from './kv-adapter'
+
+export { type KvAdapter, kvAdapter }
+export type { KvOptions } from './options'
+
+/** The `[cache.cloudflare]` table (`kv_binding`, `kv_min_ttl_s`) → the adapter. */
+const factory: CacheAdapterFactory = (table) => kvAdapter(fromTable(table, 'cloudflare-kv').kv)
+export default factory

package/src/options.ts

@@ -0,0 +1,34 @@
+import { onlyKeys } from './env'
+
+export interface KvOptions { binding?: string; min_ttl_s?: number }
+export interface DoOptions { binding?: string; store?: boolean }
+
+const str = (v: unknown, what: string) => {
+  if (typeof v !== 'string' || !v) throw new TypeError(`${what} must be a non-empty string`)
+  return v
+}
+
+/** `kvAdapter({ binding, min_ttl_s })`. */
+export function parseKv(o: KvOptions): { binding: string; minTtlS: number } {
+  onlyKeys(o as Record<string, unknown>, ['binding', 'min_ttl_s'], [], 'cloudflare-kv')
+  const minTtlS = o.min_ttl_s ?? 300
+  if (typeof minTtlS !== 'number' || !Number.isInteger(minTtlS) || minTtlS < 0 || minTtlS > 31_536_000) throw new TypeError('cloudflare-kv: min_ttl_s must be an integer in 0..31536000')
+  return { binding: o.binding === undefined ? 'BRUST_CACHE' : str(o.binding, 'cloudflare-kv: binding'), minTtlS }
+}
+
+/** `doAdapter({ binding, store })`. */
+export function parseDo(o: DoOptions): { binding: string; store: boolean } {
+  onlyKeys(o as Record<string, unknown>, ['binding', 'store'], [], 'cloudflare-do')
+  if (o.store !== undefined && typeof o.store !== 'boolean') throw new TypeError('cloudflare-do: store must be a boolean')
+  return { binding: o.binding === undefined ? 'BRUST_CACHE_DO' : str(o.binding, 'cloudflare-do: binding'), store: o.store ?? false }
+}
+
+/** The shared `[cache.cloudflare]` table (spec §6 keys) → each adapter's programmatic form; unknown keys are TypeErrors. */
+const TABLE = ['kv_binding', 'kv_min_ttl_s', 'do_binding', 'do_store']
+export function fromTable(t: Record<string, unknown>, what: string): { kv: KvOptions; do: DoOptions } {
+  onlyKeys(t, TABLE, [], what)
+  return {
+    kv: { ...(t.kv_binding !== undefined ? { binding: t.kv_binding as string } : {}), ...(t.kv_min_ttl_s !== undefined ? { min_ttl_s: t.kv_min_ttl_s as number } : {}) },
+    do: { ...(t.do_binding !== undefined ? { binding: t.do_binding as string } : {}), ...(t.do_store !== undefined ? { store: t.do_store as boolean } : {}) },
+  }
+}

package/src/ring.ts

@@ -0,0 +1,36 @@
+// The epoch ring: events with strictly increasing seqs, bounded by count and bytes. Mirrors the memory adapter's pull mode.
+import type { EpochSince, InvalidateArgs, InvalidationEvent } from '@brust/core/cache-adapter'
+
+/** An event whose JSON is larger is kept as a "clear" marker: whoever is before it gets `behind`. */
+export const OVERSIZE_EVENT = 64 * 1024
+
+interface Slot { seq: number; bytes: number; event: InvalidationEvent | null }
+
+export class Ring {
+  seq: number
+  private slots: Slot[] = []
+  private used = 0
+  /** The highest seq no longer retained. */
+  private dropped = 0
+  constructor(readonly gen: string, startSeq = 0, private capEntries = 1024, private capBytes = 1 << 20) {
+    this.seq = startSeq
+  }
+  publish(args: InvalidateArgs, origin: string): number {
+    this.seq += 1
+    const event: InvalidationEvent = { seq: this.seq, origin, args: structuredClone(args) }
+    const bytes = JSON.stringify(event).length
+    this.slots.push({ seq: this.seq, bytes: Math.min(bytes, OVERSIZE_EVENT), event: bytes > OVERSIZE_EVENT ? null : event })
+    this.used += this.slots[this.slots.length - 1]!.bytes
+    while (this.slots.length > this.capEntries || this.used > this.capBytes) {
+      const old = this.slots.shift()!
+      this.used -= old.bytes
+      this.dropped = old.seq
+    }
+    return this.seq
+  }
+  since(from: number): EpochSince {
+    const after = this.slots.filter((s) => s.seq > from)
+    const behind = from < this.dropped || from > this.seq || after.some((s) => s.event === null)
+    return { gen: this.gen, seq: this.seq, behind, events: behind ? [] : after.map((s) => structuredClone(s.event!)) }
+  }
+}