@huynle/hub 0.6.1 → 0.7.2

package/src/central/backend/file-state.ts

@@ -0,0 +1,240 @@
+// StateStore in files under <stateDir>/agent/ (the single-process hub's durable agent data; a cluster uses
+// Postgres). One JSON file per user and collection (users/<user>/<collection>.json) and one per claim namespace
+// (claims/<namespace>.json), loaded on first use and then served from memory. Changed files are written once
+// `debounceMs` after the first change, or at once by flush() (the hub flushes on stop).
+// Files are written atomically (temp file + rename) with mode 0600, folders 0700. Ids and names become path
+// segments only when they are short lowercase [a-z0-9_-] (case-insensitive file systems), otherwise their
+// SHA-256; each file repeats the ids it belongs to, so a file is never read for the wrong one. Hubs from before
+// this store ignore the folder.
+import { createHash } from "node:crypto"
+import { chmodSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs"
+import path from "node:path"
+import { realTimers } from "./memory-bus"
+import type { Claim, ClaimResult, Clock, Data, Entry, StateStore, Timers, Versioned, WriteOptions, WriteResult } from "./types"
+
+/** The folder under the state directory. */
+export const AGENT_STATE_DIR = "agent"
+/** Default delay between a change and its write. */
+export const FILE_STATE_DEBOUNCE_MS = 250
+
+export interface FileStateStoreOptions {
+  /** The hub's state directory; data goes to <stateDir>/agent/. */
+  readonly stateDir: string
+  readonly now?: Clock
+  /** Timers for the debounced writes (default real, unref'd timers). */
+  readonly timers?: Timers
+  /** Delay between a change and its write (default FILE_STATE_DEBOUNCE_MS). */
+  readonly debounceMs?: number
+  /** Reports a failed debounced write (default console.warn); the change is kept for the next write. */
+  readonly warn?: (message: string) => void
+}
+
+interface Stored {
+  value: Data
+  version: number
+}
+
+interface StoredClaim {
+  owner: string
+  at: number
+}
+
+/** A loaded file: the ids it belongs to and its items by key. */
+interface Doc<T> {
+  readonly file: string
+  readonly ids: Readonly<Record<string, string>>
+  readonly items: Map<string, T>
+}
+
+const SAFE_SEGMENT = /^[a-z0-9_-]{1,64}$/
+
+/** A file-system-safe, case-insensitive-safe path segment for an id or name. */
+const segment = (name: string): string => (SAFE_SEGMENT.test(name) ? name : `~${createHash("sha256").update(name).digest("hex")}`)
+
+export class FileStateStore implements StateStore {
+  private readonly now: Clock
+  private readonly root: string
+  private readonly timers: Timers
+  private readonly debounceMs: number
+  private readonly warn: (message: string) => void
+  /** The pending debounced write. */
+  private timer: unknown
+  /** file → loaded document. */
+  private readonly docs = new Map<string, Doc<unknown>>()
+  private readonly dirty = new Set<Doc<unknown>>()
+  /** Folders already created and restricted. */
+  private readonly folders = new Set<string>()
+
+  constructor(options: FileStateStoreOptions) {
+    this.now = options.now ?? Date.now
+    this.root = path.join(options.stateDir, AGENT_STATE_DIR)
+    this.timers = options.timers ?? realTimers
+    this.debounceMs = options.debounceMs ?? FILE_STATE_DEBOUNCE_MS
+    this.warn = options.warn ?? console.warn
+  }
+
+  async get<T = Data>(userID: string, collection: string, key: string): Promise<Versioned<T> | undefined> {
+    const stored = this.entries(userID, collection).items.get(key)
+    return stored && { value: structuredClone(stored.value) as T, version: stored.version }
+  }
+
+  async put<T = Data>(userID: string, collection: string, key: string, value: T, options: WriteOptions = {}): Promise<WriteResult> {
+    const doc = this.entries(userID, collection)
+    const current = doc.items.get(key)?.version ?? 0
+    if (options.ifVersion !== undefined && options.ifVersion !== current) return { ok: false, version: current }
+    const version = current + 1
+    doc.items.set(key, { value: structuredClone(value), version })
+    this.changed(doc)
+    return { ok: true, version }
+  }
+
+  async delete(userID: string, collection: string, key: string, options: WriteOptions = {}): Promise<WriteResult> {
+    const doc = this.entries(userID, collection)
+    const current = doc.items.get(key)?.version ?? 0
+    if (options.ifVersion !== undefined && options.ifVersion !== current) return { ok: false, version: current }
+    if (doc.items.delete(key)) this.changed(doc)
+    return { ok: true, version: 0 }
+  }
+
+  async list<T = Data>(userID: string, collection: string): Promise<Entry<T>[]> {
+    return [...this.entries(userID, collection).items.entries()]
+      .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
+      .map(([key, stored]) => ({ key, value: structuredClone(stored.value) as T, version: stored.version }))
+  }
+
+  async claim(namespace: string, key: string, owner: string): Promise<ClaimResult> {
+    const doc = this.claims(namespace)
+    const held = doc.items.get(key)
+    if (held) return held.owner === owner ? { ok: true, claim: { namespace, key, ...held } } : { ok: false, conflict: { namespace, key, ...held } }
+    const claim: Claim = { namespace, key, owner, at: this.now() }
+    doc.items.set(key, { owner, at: claim.at })
+    this.changed(doc)
+    return { ok: true, claim }
+  }
+
+  async release(namespace: string, key: string, owner: string): Promise<boolean> {
+    const doc = this.claims(namespace)
+    if (doc.items.get(key)?.owner !== owner) return false
+    doc.items.delete(key)
+    this.changed(doc)
+    return true
+  }
+
+  async claimOf(namespace: string, key: string): Promise<Claim | undefined> {
+    const held = this.claims(namespace).items.get(key)
+    return held && { namespace, key, ...held }
+  }
+
+  /** Writes every changed file now (rejects when one cannot be written; it stays changed). */
+  async flush(): Promise<void> {
+    this.writeChanged()
+  }
+
+  private writeChanged(): void {
+    if (this.timer !== undefined) this.timers.clear(this.timer)
+    this.timer = undefined
+    for (const doc of [...this.dirty]) {
+      this.write(doc)
+      this.dirty.delete(doc)
+    }
+  }
+
+  private entries(userID: string, collection: string): Doc<Stored> {
+    const file = path.join(this.root, "users", segment(userID), `${segment(collection)}.json`)
+    return this.doc<Stored>(file, { userID, collection }, (item) => {
+      const { value, version } = item
+      if (!Number.isSafeInteger(version) || (version as number) < 1) return undefined
+      return { value, version: version as number }
+    })
+  }
+
+  private claims(namespace: string): Doc<StoredClaim> {
+    const file = path.join(this.root, "claims", `${segment(namespace)}.json`)
+    return this.doc<StoredClaim>(file, { namespace }, (item) => {
+      const { owner, at } = item
+      if (typeof owner !== "string" || typeof at !== "number") return undefined
+      return { owner, at }
+    })
+  }
+
+  /** The loaded document for a file, reading it on first use. */
+  private doc<T>(file: string, ids: Record<string, string>, parse: (item: Record<string, unknown>) => T | undefined): Doc<T> {
+    const loaded = this.docs.get(file) as Doc<T> | undefined
+    if (loaded) {
+      for (const [name, id] of Object.entries(ids)) if (loaded.ids[name] !== id) throw new Error(`${file} belongs to another ${name}`)
+      return loaded
+    }
+    const doc: Doc<T> = { file, ids, items: read(file, ids, parse) }
+    this.docs.set(file, doc as Doc<unknown>)
+    return doc
+  }
+
+  private changed(doc: Doc<unknown>): void {
+    this.dirty.add(doc)
+    if (this.timer !== undefined) return
+    this.timer = this.timers.set(() => {
+      this.timer = undefined
+      try {
+        this.writeChanged()
+      } catch (cause) {
+        this.warn(`[hub] cannot write agent state under ${this.root}: ${(cause as Error).message}; retrying on the next change`)
+      }
+    }, this.debounceMs)
+  }
+
+  private write(doc: Doc<unknown>): void {
+    if (doc.items.size === 0) {
+      rmSync(doc.file, { force: true })
+      return
+    }
+    this.folder(path.dirname(doc.file))
+    const items = [...doc.items.entries()].map(([key, item]) => ({ key, ...(item as object) }))
+    const tmp = `${doc.file}.${process.pid}.tmp`
+    writeFileSync(tmp, `${JSON.stringify({ ...doc.ids, items })}\n`, { mode: 0o600 })
+    chmodSync(tmp, 0o600)
+    renameSync(tmp, doc.file)
+  }
+
+  /** Creates a folder under the root (and the root) restricted to the owner. */
+  private folder(dir: string): void {
+    if (this.folders.has(dir)) return
+    if (dir !== this.root) this.folder(path.dirname(dir))
+    mkdirSync(dir, { recursive: true, mode: 0o700 })
+    chmodSync(dir, 0o700)
+    this.folders.add(dir)
+  }
+}
+
+/** A file's items, or none when it does not exist; throws (naming the file, never its content) when invalid. */
+function read<T>(file: string, ids: Record<string, string>, parse: (item: Record<string, unknown>) => T | undefined): Map<string, T> {
+  let text: string
+  try {
+    text = readFileSync(file, "utf8")
+  } catch (cause) {
+    if ((cause as NodeJS.ErrnoException | undefined)?.code === "ENOENT") return new Map()
+    throw cause
+  }
+  const fail = (why: string): never => {
+    throw new Error(`Invalid ${file}: ${why}. Fix or move it away.`)
+  }
+  let raw: unknown
+  try {
+    raw = JSON.parse(text)
+  } catch {
+    return fail("not valid JSON")
+  }
+  if (typeof raw !== "object" || raw === null) return fail("not an object")
+  const record = raw as Record<string, unknown>
+  for (const [name, id] of Object.entries(ids)) if (record[name] !== id) fail(`${name} does not match`)
+  if (!Array.isArray(record.items)) return fail("no items")
+  const items = new Map<string, T>()
+  for (const entry of record.items as unknown[]) {
+    if (typeof entry !== "object" || entry === null) return fail("an item is not an object")
+    const { key, ...rest } = entry as Record<string, unknown>
+    if (typeof key !== "string") return fail("an item has no key")
+    const item = parse(rest)
+    if (item === undefined) return fail("an item is malformed")
+    items.set(key, item)
+  }
+  return items
+}

package/src/central/backend/index.ts

@@ -0,0 +1,116 @@
+// The hub's backends (design §9): interfaces in ./types, in-memory implementations for the single-process hub,
+// a file StateStore under <stateDir>/agent, and the cluster bundle (Postgres + Valkey). startCentral creates the bundle its config selects (hubBackends:
+// file, or cluster when HUB_DATABASE_URL/HUB_VALKEY_URL are set) or takes one in its options, exposes it to
+// new code only, and flushes its state on stop.
+import { FileStateStore, type FileStateStoreOptions } from "./file-state"
+import { MemoryBus } from "./memory-bus"
+import { MemoryCatalog } from "./memory-catalog"
+import { MemoryCounters, MemoryLocks } from "./memory-counters"
+import { AGENT_EVENTS_AGE_MS, AGENT_EVENTS_MAX } from "../agent/events"
+import { MemoryEventLog } from "./memory-events"
+import { MemoryKv } from "./memory-kv"
+import { MemoryStateStore } from "./memory-state"
+import { randomUUID } from "node:crypto"
+import { RedisClient } from "bun"
+import { PostgresStateStore } from "./postgres-state"
+import { ValkeyBus } from "./valkey-bus"
+import { ValkeyCatalog } from "./valkey-catalog"
+import { ValkeyCounters } from "./valkey-counters"
+import { ValkeyEventLog } from "./valkey-events"
+import { ValkeyKv } from "./valkey-kv"
+import { ValkeyLocks } from "./valkey-locks"
+import type { CentralConfig, ClusterConfig } from "../config"
+import type { Backends, Clock, Timers } from "./types"
+
+export * from "./types"
+
+export interface MemoryBackendsOptions {
+  /** The clock every backend reads (default Date.now). */
+  readonly now?: Clock
+  /** Timers for bus request timeouts (default real, unref'd timers). */
+  readonly timers?: Timers
+}
+
+/** Every backend in process memory, on one clock. */
+export function memoryBackends(options: MemoryBackendsOptions = {}): Backends {
+  const now = options.now ?? Date.now
+  return {
+    state: new MemoryStateStore({ now }),
+    bus: new MemoryBus(options.timers ? { timers: options.timers } : {}),
+    events: new MemoryEventLog({ now }),
+    agentEvents: new MemoryEventLog({ now, max: AGENT_EVENTS_MAX, maxAgeMs: AGENT_EVENTS_AGE_MS }),
+    counters: new MemoryCounters({ now }),
+    locks: new MemoryLocks({ now }),
+    catalog: new MemoryCatalog({ now }),
+    kv: new MemoryKv({ now }),
+  }
+}
+
+
+export interface FileBackendsOptions extends MemoryBackendsOptions, Pick<FileStateStoreOptions, "debounceMs" | "warn"> {
+  /** The hub's state directory; the StateStore writes under <stateDir>/agent. */
+  readonly stateDir: string
+}
+
+/** The StateStore in files under the state directory, every other backend in process memory, on one clock. */
+export function fileBackends(options: FileBackendsOptions): Backends {
+  const { stateDir, debounceMs, warn, ...memory } = options
+  const state = new FileStateStore({
+    stateDir,
+    ...(memory.now ? { now: memory.now } : {}),
+    ...(memory.timers ? { timers: memory.timers } : {}),
+    ...(debounceMs !== undefined ? { debounceMs } : {}),
+    ...(warn ? { warn } : {}),
+  })
+  return { ...memoryBackends(memory), state }
+}
+
+export interface ClusterBackendsOptions extends MemoryBackendsOptions {
+  /** HUB_DATABASE_URL / HUB_VALKEY_URL and the pod id (see ../config). */
+  readonly cluster: ClusterConfig
+  /** Opens the Valkey client kv, counters, locks, events and catalog share (default: Bun.RedisClient; tests). */
+  readonly valkeyClient?: (url: string) => RedisClient
+}
+
+/**
+ * State in Postgres, everything else in Valkey (design §9). Built synchronously, nothing connects until first
+ * use: the Postgres pool checks the schema then (it never migrates: `hub-server migrate` does), and one Valkey
+ * client, opened on the first command, serves kv, counters, locks, events and catalog; the bus opens its own
+ * (pub/sub needs dedicated connections). close() closes them all. URLs are never put in a message.
+ */
+export function clusterBackends(options: ClusterBackendsOptions): Backends {
+  const { cluster } = options
+  const now = options.now
+  const open = options.valkeyClient ?? ((url: string) => new RedisClient(url))
+  let client: RedisClient | undefined
+  // One lazily opened client behind the shape the Valkey backends use (send / close).
+  const shared = {
+    send: (command: string, args: string[]) => (client ??= open(cluster.valkeyURL)).send(command, args),
+    close: () => {
+      client?.close()
+      client = undefined
+    },
+  } as unknown as RedisClient
+  const state = new PostgresStateStore({ url: cluster.databaseURL, ...(now ? { now } : {}) })
+  const bus = new ValkeyBus(cluster.valkeyURL, { instanceID: `${cluster.podID}-${randomUUID().slice(0, 8)}`, ...(options.timers ? { timers: options.timers } : {}) })
+  return {
+    state,
+    bus,
+    events: new ValkeyEventLog(shared, now ? { now } : {}),
+    agentEvents: new ValkeyEventLog(shared, { ...(now ? { now } : {}), max: AGENT_EVENTS_MAX, maxAgeMs: AGENT_EVENTS_AGE_MS, prefix: "hub:agent:" }),
+    counters: new ValkeyCounters(shared),
+    locks: new ValkeyLocks(shared, now ? { now } : {}),
+    catalog: new ValkeyCatalog(shared, now ? { now } : {}),
+    kv: new ValkeyKv(shared),
+    async close() {
+      bus.close()
+      shared.close()
+      await state.close()
+    },
+  }
+}
+
+/** The hub's bundle for its config: the cluster one when cluster mode is configured, else the file one. */
+export function hubBackends(config: Pick<CentralConfig, "stateDir" | "cluster">, options: MemoryBackendsOptions = {}): Backends {
+  return config.cluster ? clusterBackends({ ...options, cluster: config.cluster }) : fileBackends({ ...options, stateDir: config.stateDir })
+}

package/src/central/backend/memory-bus.ts

@@ -0,0 +1,93 @@
+// Bus in process memory (a cluster uses Valkey/Redis pub/sub). Messages are copied, like a network hop, so
+// publisher and subscribers never share objects. publish resolves once every subscriber has handled the message
+// here; callers must not rely on that (a networked bus resolves on send).
+import { BusNoResponderError, BusRemoteError, BusTimeoutError, type Bus, type BusHandler, type BusResponder, type Data, type RequestOptions, type Timers, type Unsubscribe } from "./types"
+
+/** setTimeout-based timers that never keep the process alive. */
+export const realTimers: Timers = {
+  set: (fn, ms) => {
+    const handle = setTimeout(fn, ms)
+    ;(handle as { unref?: () => void }).unref?.()
+    return handle
+  },
+  clear: (handle) => clearTimeout(handle as ReturnType<typeof setTimeout>),
+}
+
+export interface MemoryBusOptions {
+  /** Request timeouts (injectable for tests). */
+  readonly timers?: Timers
+  /** Called with a subscriber's error (default: logged). */
+  readonly onError?: (error: unknown, topic: string) => void
+}
+
+export class MemoryBus implements Bus {
+  private readonly timers: Timers
+  private readonly onError: (error: unknown, topic: string) => void
+  private readonly subscribers = new Map<string, Set<BusHandler>>()
+  private readonly responders = new Map<string, BusResponder>()
+
+  constructor(options: MemoryBusOptions = {}) {
+    this.timers = options.timers ?? realTimers
+    this.onError = options.onError ?? ((error, topic) => console.error(`hub: bus subscriber on ${topic} failed:`, error))
+  }
+
+  async publish(topic: string, message: Data): Promise<number> {
+    const handlers = [...(this.subscribers.get(topic) ?? [])]
+    await Promise.all(
+      handlers.map(async (handler) => {
+        try {
+          await handler(structuredClone(message), topic)
+        } catch (error) {
+          this.onError(error, topic)
+        }
+      }),
+    )
+    return handlers.length
+  }
+
+  async subscribe(topic: string, handler: BusHandler): Promise<Unsubscribe> {
+    let handlers = this.subscribers.get(topic)
+    if (!handlers) this.subscribers.set(topic, (handlers = new Set()))
+    // Wrapped so subscribing one function twice gives two independent subscriptions.
+    const subscription: BusHandler = (message, t) => handler(message, t)
+    handlers.add(subscription)
+    return async () => {
+      const current = this.subscribers.get(topic)
+      current?.delete(subscription)
+      if (current?.size === 0) this.subscribers.delete(topic)
+    }
+  }
+
+  async serve(topic: string, responder: BusResponder): Promise<Unsubscribe> {
+    if (this.responders.has(topic)) throw new Error(`already serving ${topic}`)
+    this.responders.set(topic, responder)
+    return async () => {
+      if (this.responders.get(topic) === responder) this.responders.delete(topic)
+    }
+  }
+
+  request<T = Data>(topic: string, message: Data, options: RequestOptions): Promise<T> {
+    const responder = this.responders.get(topic)
+    if (!responder) return Promise.reject(new BusNoResponderError(topic))
+    return new Promise<T>((resolve, reject) => {
+      let settled = false
+      const timer = this.timers.set(() => {
+        if (settled) return
+        settled = true
+        reject(new BusTimeoutError(topic, options.timeoutMs))
+      }, options.timeoutMs)
+      const settle = (fn: () => void) => {
+        if (settled) return
+        settled = true
+        this.timers.clear(timer)
+        fn()
+      }
+      Promise.resolve()
+        .then(() => responder(structuredClone(message), topic))
+        .then(
+          (reply) => settle(() => resolve(structuredClone(reply) as T)),
+          (error) => settle(() => reject(new BusRemoteError(topic, error instanceof Error ? error.message : String(error)))),
+        )
+    })
+  }
+}

package/src/central/backend/memory-catalog.ts

@@ -0,0 +1,90 @@
+// Catalog in process memory (a cluster uses one Redis hash per user). Each connection's report of a session is
+// kept apart, keyed by (sessionID, connID), and merged when read, so every process writes only its own reports.
+// Reports with a ttl expire lazily against the clock.
+import type { Catalog, CatalogEntry, CatalogSession, CatalogValue, Clock } from "./types"
+
+/** Combines a session's reports (oldest first) into one value. */
+export type CatalogMerge = (entries: CatalogEntry[]) => CatalogValue
+
+/** Default merge: a shallow merge in report order, so the newest report wins per field. */
+export const mergeNewestWins: CatalogMerge = (entries) => Object.assign({}, ...entries.map((entry) => entry.value))
+
+interface Report extends CatalogEntry {
+  readonly expiresAt?: number
+}
+
+const reportKey = (sessionID: string, connID: string) => `${sessionID}\u0000${connID}`
+
+export class MemoryCatalog implements Catalog {
+  private readonly now: Clock
+  private readonly merge: CatalogMerge
+  /** userID → reportKey → report, in report order (a new report moves to the end). */
+  private readonly users = new Map<string, Map<string, Report>>()
+
+  constructor(options: { now?: Clock; merge?: CatalogMerge } = {}) {
+    this.now = options.now ?? Date.now
+    this.merge = options.merge ?? mergeNewestWins
+  }
+
+  async set(userID: string, sessionID: string, connID: string, value: CatalogValue, options: { readonly ttlMs?: number } = {}): Promise<void> {
+    let reports = this.users.get(userID)
+    if (!reports) this.users.set(userID, (reports = new Map()))
+    const at = this.now()
+    const key = reportKey(sessionID, connID)
+    reports.delete(key)
+    reports.set(key, { sessionID, connID, value: structuredClone(value), at, ...(options.ttlMs !== undefined ? { expiresAt: at + options.ttlMs } : {}) })
+  }
+
+  async delete(userID: string, sessionID: string, connID?: string): Promise<void> {
+    this.remove(userID, (report) => report.sessionID === sessionID && (connID === undefined || report.connID === connID))
+  }
+
+  async deleteConn(userID: string, connID: string): Promise<void> {
+    this.remove(userID, (report) => report.connID === connID)
+  }
+
+  async get(userID: string, sessionID: string): Promise<CatalogSession | undefined> {
+    const reports = this.live(userID).filter((report) => report.sessionID === sessionID)
+    return reports.length ? this.session(sessionID, reports) : undefined
+  }
+
+  async list(userID: string): Promise<CatalogSession[]> {
+    const bySession = new Map<string, CatalogEntry[]>()
+    for (const report of this.live(userID)) {
+      const reports = bySession.get(report.sessionID)
+      if (reports) reports.push(report)
+      else bySession.set(report.sessionID, [report])
+    }
+    return [...bySession.keys()].sort().map((sessionID) => this.session(sessionID, bySession.get(sessionID)!))
+  }
+
+  async entries(userID: string): Promise<CatalogEntry[]> {
+    return this.live(userID).map(({ sessionID, connID, value, at }) => ({ sessionID, connID, value: structuredClone(value), at }))
+  }
+
+  /** The user's unexpired reports in report order (expired ones are dropped). */
+  private live(userID: string): Report[] {
+    const reports = this.users.get(userID)
+    if (!reports) return []
+    const t = this.now()
+    for (const [key, report] of reports) if (report.expiresAt !== undefined && report.expiresAt <= t) reports.delete(key)
+    if (!reports.size) this.users.delete(userID)
+    return [...reports.values()]
+  }
+
+  private session(sessionID: string, reports: CatalogEntry[]): CatalogSession {
+    return {
+      sessionID,
+      value: structuredClone(this.merge(reports)),
+      connIDs: reports.map((report) => report.connID),
+      at: Math.max(...reports.map((report) => report.at)),
+    }
+  }
+
+  private remove(userID: string, match: (report: Report) => boolean): void {
+    const reports = this.users.get(userID)
+    if (!reports) return
+    for (const [key, report] of reports) if (match(report)) reports.delete(key)
+    if (!reports.size) this.users.delete(userID)
+  }
+}

package/src/central/backend/memory-counters.ts

@@ -0,0 +1,102 @@
+// Counters and Locks in process memory (a cluster uses Redis INCR + PEXPIRE NX and SET NX PX). Expiry is
+// evaluated lazily against the clock: no timers. Expired keys are dropped when touched and in periodic sweeps,
+// so keys that are never read again do not pile up.
+import type { Clock, Counters, Lease, Locks } from "./types"
+
+/** Writes between sweeps of expired keys. */
+const SWEEP_EVERY = 1000
+
+/** A map whose entries expire at `expiresAt`; reads drop expired entries. */
+export class ExpiringMap<V extends { readonly expiresAt: number }> {
+  private readonly entries = new Map<string, V>()
+  private writes = 0
+
+  constructor(private readonly now: Clock) {}
+
+  get(key: string): V | undefined {
+    const entry = this.entries.get(key)
+    if (entry && entry.expiresAt <= this.now()) {
+      this.entries.delete(key)
+      return undefined
+    }
+    return entry
+  }
+
+  set(key: string, value: V): void {
+    this.entries.set(key, value)
+    if (++this.writes % SWEEP_EVERY === 0) this.sweep()
+  }
+
+  delete(key: string): void {
+    this.entries.delete(key)
+  }
+
+  private sweep(): void {
+    const t = this.now()
+    for (const [key, entry] of this.entries) if (entry.expiresAt <= t) this.entries.delete(key)
+  }
+}
+
+export class MemoryCounters implements Counters {
+  private readonly now: Clock
+  private readonly counts: ExpiringMap<{ count: number; expiresAt: number }>
+
+  constructor(options: { now?: Clock } = {}) {
+    this.now = options.now ?? Date.now
+    this.counts = new ExpiringMap(this.now)
+  }
+
+  async incr(key: string, ttlMs: number): Promise<number> {
+    const current = this.counts.get(key)
+    const count = (current?.count ?? 0) + 1
+    this.counts.set(key, { count, expiresAt: current?.expiresAt ?? this.now() + ttlMs })
+    return count
+  }
+
+  async get(key: string): Promise<number> {
+    return this.counts.get(key)?.count ?? 0
+  }
+}
+
+export class MemoryLocks implements Locks {
+  private readonly now: Clock
+  private readonly leases: ExpiringMap<Lease>
+  /** Last fence handed out per key (kept after release so fences only grow). */
+  private readonly fences = new Map<string, number>()
+
+  constructor(options: { now?: Clock } = {}) {
+    this.now = options.now ?? Date.now
+    this.leases = new ExpiringMap(this.now)
+  }
+
+  async acquire(key: string, owner: string, ttlMs: number): Promise<Lease | undefined> {
+    const held = this.leases.get(key)
+    if (held) return held.owner === owner ? this.extend(held, ttlMs) : undefined
+    const fence = (this.fences.get(key) ?? 0) + 1
+    this.fences.set(key, fence)
+    const lease: Lease = { key, owner, fence, expiresAt: this.now() + ttlMs }
+    this.leases.set(key, lease)
+    return lease
+  }
+
+  async renew(key: string, owner: string, ttlMs: number): Promise<Lease | undefined> {
+    const held = this.leases.get(key)
+    return held?.owner === owner ? this.extend(held, ttlMs) : undefined
+  }
+
+  async release(key: string, owner: string): Promise<boolean> {
+    if (this.leases.get(key)?.owner !== owner) return false
+    this.leases.delete(key)
+    return true
+  }
+
+  async holder(key: string): Promise<Lease | undefined> {
+    return this.leases.get(key)
+  }
+
+  private extend(lease: Lease, ttlMs: number): Lease {
+    const renewed = { ...lease, expiresAt: this.now() + ttlMs }
+    this.leases.set(lease.key, renewed)
+    return renewed
+  }
+}

package/src/central/backend/memory-events.ts

@@ -0,0 +1,45 @@
+// EventLog in process memory (a cluster uses Redis Streams). Same semantics and bounds as the live stream's log
+// (../events-log.ts), which it reuses as its ring; it is a separate instance, the live stream keeps its own.
+import { EventLog as Ring, EVENT_LOG_AGE_MS, EVENT_LOG_MAX } from "../events-log"
+import type { Clock, EventLog, EventMessage, LogEvent, SinceResult } from "./types"
+
+export interface MemoryEventLogOptions {
+  readonly now?: Clock
+  /** Events kept per user (default EVENT_LOG_MAX). */
+  readonly max?: number
+  /** Events older than this are dropped (default EVENT_LOG_AGE_MS). */
+  readonly maxAgeMs?: number
+  /** Id prefix; new for every instance by default, so ids from another run are never mistaken for current ones. */
+  readonly epoch?: string
+}
+
+const newEpoch = () => `${Date.now().toString(36)}${crypto.randomUUID().replaceAll("-", "").slice(0, 8)}`
+
+export class MemoryEventLog implements EventLog {
+  private readonly ring: Ring
+
+  constructor(options: MemoryEventLogOptions = {}) {
+    this.ring = new Ring({
+      max: options.max ?? EVENT_LOG_MAX,
+      maxAgeMs: options.maxAgeMs ?? EVENT_LOG_AGE_MS,
+      now: options.now ?? Date.now,
+      epoch: options.epoch ?? newEpoch(),
+    })
+  }
+
+  async append(userID: string, message: EventMessage, options: { readonly exceptDevice?: string } = {}): Promise<string> {
+    return this.ring.append(userID, structuredClone(message), options.exceptDevice)
+  }
+
+  async latest(userID: string): Promise<string> {
+    // Opening the user's log lets a client holding this id be covered before the first event.
+    this.ring.open(userID)
+    return this.ring.latest(userID)
+  }
+
+  async since(userID: string, lastID: string): Promise<SinceResult> {
+    const events = this.ring.since(userID, lastID)
+    if (!events) return { resync: true }
+    return { events: events.map((event): LogEvent => structuredClone(event)) }
+  }
+}