@huynle/hub 0.6.1 → 0.7.1

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

@@ -0,0 +1,38 @@
+// Kv in process memory (a cluster uses Valkey SET [PX] [NX], GET, GETDEL, DEL). Expiry is evaluated lazily
+// against the clock, like the counters: no timers; expired keys are dropped when touched and in periodic sweeps.
+import { ExpiringMap } from "./memory-counters"
+import type { Clock, Kv, KvSetOptions } from "./types"
+
+export class MemoryKv implements Kv {
+  private readonly now: Clock
+  private readonly values: ExpiringMap<{ value: string; expiresAt: number }>
+
+  constructor(options: { now?: Clock } = {}) {
+    this.now = options.now ?? Date.now
+    this.values = new ExpiringMap(this.now)
+  }
+
+  async set(key: string, value: string, options: KvSetOptions = {}): Promise<boolean> {
+    const { px, nx } = options
+    if (px !== undefined && !(Number.isInteger(px) && px > 0)) throw new Error("Kv.set: px must be a positive whole number of milliseconds")
+    if (nx && this.values.get(key)) return false
+    this.values.set(key, { value, expiresAt: px === undefined ? Infinity : this.now() + px })
+    return true
+  }
+
+  async get(key: string): Promise<string | undefined> {
+    return this.values.get(key)?.value
+  }
+
+  async getdel(key: string): Promise<string | undefined> {
+    const entry = this.values.get(key)
+    if (entry) this.values.delete(key)
+    return entry?.value
+  }
+
+  async del(key: string): Promise<boolean> {
+    const existed = this.values.get(key) !== undefined
+    this.values.delete(key)
+    return existed
+  }
+}

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

@@ -0,0 +1,77 @@
+// StateStore in process memory (the single-process hub; a cluster uses Postgres). Values are copied in and out,
+// like a database round trip, so callers never share mutable state with the store.
+import type { Claim, ClaimResult, Clock, Data, Entry, StateStore, Versioned, WriteOptions, WriteResult } from "./types"
+
+interface Stored {
+  value: Data
+  version: number
+}
+
+/** Map key for (a, b) pairs; NUL never occurs in ids or names. */
+const pair = (a: string, b: string) => `${a}\u0000${b}`
+
+export class MemoryStateStore implements StateStore {
+  private readonly now: Clock
+  /** pair(userID, collection) → key → entry. */
+  private readonly collections = new Map<string, Map<string, Stored>>()
+  /** pair(namespace, key) → claim. */
+  private readonly claims = new Map<string, Claim>()
+
+  constructor(options: { now?: Clock } = {}) {
+    this.now = options.now ?? Date.now
+  }
+
+  async get<T = Data>(userID: string, collection: string, key: string): Promise<Versioned<T> | undefined> {
+    const stored = this.collections.get(pair(userID, collection))?.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 id = pair(userID, collection)
+    let entries = this.collections.get(id)
+    const current = entries?.get(key)?.version ?? 0
+    if (options.ifVersion !== undefined && options.ifVersion !== current) return { ok: false, version: current }
+    if (!entries) this.collections.set(id, (entries = new Map()))
+    const version = current + 1
+    entries.set(key, { value: structuredClone(value), version })
+    return { ok: true, version }
+  }
+
+  async delete(userID: string, collection: string, key: string, options: WriteOptions = {}): Promise<WriteResult> {
+    const id = pair(userID, collection)
+    const entries = this.collections.get(id)
+    const current = entries?.get(key)?.version ?? 0
+    if (options.ifVersion !== undefined && options.ifVersion !== current) return { ok: false, version: current }
+    entries?.delete(key)
+    if (entries?.size === 0) this.collections.delete(id)
+    return { ok: true, version: 0 }
+  }
+
+  async list<T = Data>(userID: string, collection: string): Promise<Entry<T>[]> {
+    const entries = this.collections.get(pair(userID, collection))
+    if (!entries) return []
+    return [...entries.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 id = pair(namespace, key)
+    const held = this.claims.get(id)
+    if (held) return held.owner === owner ? { ok: true, claim: held } : { ok: false, conflict: held }
+    const claim: Claim = { namespace, key, owner, at: this.now() }
+    this.claims.set(id, claim)
+    return { ok: true, claim }
+  }
+
+  async release(namespace: string, key: string, owner: string): Promise<boolean> {
+    const id = pair(namespace, key)
+    if (this.claims.get(id)?.owner !== owner) return false
+    this.claims.delete(id)
+    return true
+  }
+
+  async claimOf(namespace: string, key: string): Promise<Claim | undefined> {
+    return this.claims.get(pair(namespace, key))
+  }
+}

package/src/central/backend/postgres-migrate.ts

@@ -0,0 +1,100 @@
+// Postgres schema for cluster mode (decision vkxkqiuf §3, design §10). Migrations are ordered, recorded in
+// hub_schema and applied by `hub-server migrate` (a Job) under a session advisory lock, so concurrent runs apply
+// each one exactly once; each runs in its own transaction. A database newer than the code is left alone: every
+// schema must keep working with the previous release. Nothing here names the database URL.
+import type { SQL } from "bun"
+
+export interface Migration {
+  /** 1, 2, 3… in order. */
+  readonly version: number
+  readonly name: string
+  /** SQL statements, run in one transaction. */
+  readonly up: string
+}
+
+export const MIGRATIONS: readonly Migration[] = [
+  {
+    version: 1,
+    name: "state-and-claims",
+    up: `
+      CREATE TABLE hub_state (
+        user_id text COLLATE "C" NOT NULL,
+        collection text COLLATE "C" NOT NULL,
+        key text COLLATE "C" NOT NULL,
+        value jsonb NOT NULL,
+        version integer NOT NULL CHECK (version > 0),
+        updated_at timestamptz NOT NULL DEFAULT now(),
+        PRIMARY KEY (user_id, collection, key)
+      );
+      CREATE TABLE hub_claims (
+        namespace text COLLATE "C" NOT NULL,
+        key text COLLATE "C" NOT NULL,
+        owner text NOT NULL,
+        at bigint NOT NULL,
+        PRIMARY KEY (namespace, key)
+      );
+    `,
+  },
+]
+
+/** The schema version this code needs. */
+export const SCHEMA_VERSION = MIGRATIONS.at(-1)?.version ?? 0
+
+/** pg_advisory_lock key of the migrations ("hubsch" in ASCII). */
+export const MIGRATION_LOCK_KEY = 0x6875_6273_6368
+
+const SCHEMA_TABLE = `
+  CREATE TABLE IF NOT EXISTS hub_schema (
+    version integer PRIMARY KEY,
+    name text NOT NULL,
+    applied_at timestamptz NOT NULL DEFAULT now()
+  )
+`
+
+/** The database's schema version: the latest applied migration (0 before the first). */
+export async function schemaVersion(sql: SQL): Promise<number> {
+  const [exists] = (await sql`SELECT to_regclass('public.hub_schema') IS NOT NULL AS ok`) as { ok: boolean }[]
+  if (!exists?.ok) return 0
+  const [row] = (await sql`SELECT coalesce(max(version), 0)::int AS version FROM hub_schema`) as { version: number }[]
+  return row?.version ?? 0
+}
+
+export interface MigrateResult {
+  /** The versions this run applied (empty when another run or an earlier one did). */
+  readonly applied: number[]
+  /** The schema version afterwards. */
+  readonly version: number
+}
+
+/** Applies the pending migrations under the advisory lock; idempotent and safe to run concurrently. */
+export async function migrate(sql: SQL, options: { readonly migrations?: readonly Migration[] } = {}): Promise<MigrateResult> {
+  const migrations = options.migrations ?? MIGRATIONS
+  const conn = await sql.reserve()
+  try {
+    await conn`SELECT pg_advisory_lock(${String(MIGRATION_LOCK_KEY)}::bigint)`
+    try {
+      await conn.unsafe(SCHEMA_TABLE)
+      const done = new Set(((await conn`SELECT version FROM hub_schema`) as { version: number }[]).map((r) => r.version))
+      const applied: number[] = []
+      for (const migration of migrations) {
+        if (done.has(migration.version)) continue
+        // BEGIN/COMMIT by hand: Bun 1.3.5's reserved-connection begin() also leaves the failure unhandled.
+        await conn.unsafe("BEGIN")
+        try {
+          await conn.unsafe(migration.up)
+          await conn`INSERT INTO hub_schema (version, name) VALUES (${migration.version}, ${migration.name})`
+          await conn.unsafe("COMMIT")
+        } catch (error) {
+          await conn.unsafe("ROLLBACK").catch(() => {})
+          throw new Error(`migration ${migration.version} (${migration.name}) failed: ${(error as Error).message}`, { cause: error })
+        }
+        applied.push(migration.version)
+      }
+      return { applied, version: await schemaVersion(conn) }
+    } finally {
+      await conn`SELECT pg_advisory_unlock(${String(MIGRATION_LOCK_KEY)}::bigint)`
+    }
+  } finally {
+    conn.release()
+  }
+}

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

@@ -0,0 +1,197 @@
+// StateStore in Postgres (cluster mode; decision vkxkqiuf §3). Entries live in one jsonb table, hub_state
+// (user_id, collection, key, value, version); unique claims in hub_claims with the primary key as the unique
+// constraint. Versions change in single statements, so concurrent pods never lose a write:
+// - put without ifVersion: an upsert that bumps the version
+// - put with ifVersion 0: INSERT … ON CONFLICT DO NOTHING
+// - put with ifVersion n: UPDATE … WHERE version = n (a concurrent writer re-checks the row it waited for)
+// and a refused write reports the version read right after. The client connects on first use (the hub builds its
+// backends synchronously) and first checks the schema (see ./postgres-migrate), or applies it with `migrate`.
+// The URL holds credentials: it stays in a private field and is never put in a message.
+import { SQL } from "bun"
+import { migrate, SCHEMA_VERSION, schemaVersion } from "./postgres-migrate"
+import type { Claim, ClaimResult, Clock, Data, Entry, StateStore, Versioned, WriteOptions, WriteResult } from "./types"
+
+export interface PostgresStateStoreOptions {
+  /** postgres:// or postgresql:// (with credentials). */
+  readonly url: string
+  readonly now?: Clock
+  /** Apply pending migrations on first use (default false: they must have run, `hub-server migrate`). */
+  readonly migrate?: boolean
+  /** Pool size (default 10). */
+  readonly max?: number
+  /** Seconds to wait for a connection (default Bun's). */
+  readonly connectionTimeoutSeconds?: number
+}
+
+/** The database is behind the schema this hub needs. The message names no URL. */
+export class SchemaOutdatedError extends Error {
+  constructor(readonly found: number, readonly needed: number) {
+    super(`The Postgres schema is at version ${found}, this hub needs ${needed}: run \`hub-server migrate\``)
+    this.name = "SchemaOutdatedError"
+  }
+}
+
+/** Attempts of a conditional write whose row changed between the write and the version read. */
+const RACE_RETRIES = 8
+
+interface Row {
+  value: string
+  version: number
+}
+
+interface ClaimRow {
+  owner: string
+  at: number
+}
+
+export class PostgresStateStore implements StateStore {
+  readonly #url: string
+  readonly #options: Omit<PostgresStateStoreOptions, "url">
+  readonly #now: Clock
+  #sql?: SQL
+  #ready?: Promise<void>
+
+  constructor(options: PostgresStateStoreOptions) {
+    const { url, ...rest } = options
+    this.#url = url
+    this.#options = rest
+    this.#now = options.now ?? Date.now
+  }
+
+  async get<T = Data>(userID: string, collection: string, key: string): Promise<Versioned<T> | undefined> {
+    const sql = await this.#client()
+    const [row] = (await sql`
+      SELECT value::text AS value, version FROM hub_state
+      WHERE user_id = ${userID} AND collection = ${collection} AND key = ${key}`) as Row[]
+    return row && { value: JSON.parse(row.value) as T, version: row.version }
+  }
+
+  async put<T = Data>(userID: string, collection: string, key: string, value: T, options: WriteOptions = {}): Promise<WriteResult> {
+    const sql = await this.#client()
+    const json = JSON.stringify(value ?? null)
+    const expected = options.ifVersion
+    if (expected === undefined) {
+      const [row] = (await sql`
+        INSERT INTO hub_state (user_id, collection, key, value, version)
+        VALUES (${userID}, ${collection}, ${key}, (${json}::text)::jsonb, 1)
+        ON CONFLICT (user_id, collection, key)
+        DO UPDATE SET value = EXCLUDED.value, version = hub_state.version + 1, updated_at = now()
+        RETURNING version`) as { version: number }[]
+      return { ok: true, version: row!.version }
+    }
+    for (let attempt = 0; ; attempt++) {
+      const rows = (expected === 0
+        ? await sql`
+            INSERT INTO hub_state (user_id, collection, key, value, version)
+            VALUES (${userID}, ${collection}, ${key}, (${json}::text)::jsonb, 1)
+            ON CONFLICT (user_id, collection, key) DO NOTHING
+            RETURNING version`
+        : await sql`
+            UPDATE hub_state SET value = (${json}::text)::jsonb, version = version + 1, updated_at = now()
+            WHERE user_id = ${userID} AND collection = ${collection} AND key = ${key} AND version = ${expected}
+            RETURNING version`) as { version: number }[]
+      if (rows[0]) return { ok: true, version: rows[0].version }
+      const current = await this.#version(sql, userID, collection, key)
+      // The row changed back to the expected version in between (deleted and recreated): try again.
+      if (current !== expected || attempt >= RACE_RETRIES) return { ok: false, version: current }
+    }
+  }
+
+  async delete(userID: string, collection: string, key: string, options: WriteOptions = {}): Promise<WriteResult> {
+    const sql = await this.#client()
+    const expected = options.ifVersion
+    if (expected === undefined) {
+      await sql`DELETE FROM hub_state WHERE user_id = ${userID} AND collection = ${collection} AND key = ${key}`
+      return { ok: true, version: 0 }
+    }
+    for (let attempt = 0; ; attempt++) {
+      if (expected !== 0) {
+        const rows = await sql`
+          DELETE FROM hub_state
+          WHERE user_id = ${userID} AND collection = ${collection} AND key = ${key} AND version = ${expected}
+          RETURNING version`
+        if (rows.length) return { ok: true, version: 0 }
+      }
+      const current = await this.#version(sql, userID, collection, key)
+      if (expected === 0 && current === 0) return { ok: true, version: 0 }
+      if (current !== expected || attempt >= RACE_RETRIES) return { ok: false, version: current }
+    }
+  }
+
+  async list<T = Data>(userID: string, collection: string): Promise<Entry<T>[]> {
+    const sql = await this.#client()
+    const rows = (await sql`
+      SELECT key, value::text AS value, version FROM hub_state
+      WHERE user_id = ${userID} AND collection = ${collection}`) as (Row & { key: string })[]
+    // Sorted here, by UTF-16 code units like the other stores (not by a database collation).
+    return rows
+      .sort((a, b) => (a.key < b.key ? -1 : a.key > b.key ? 1 : 0))
+      .map((row) => ({ key: row.key, value: JSON.parse(row.value) as T, version: row.version }))
+  }
+
+  async claim(namespace: string, key: string, owner: string): Promise<ClaimResult> {
+    const sql = await this.#client()
+    for (let attempt = 0; ; attempt++) {
+      const [inserted] = (await sql`
+        INSERT INTO hub_claims (namespace, key, owner, at) VALUES (${namespace}, ${key}, ${owner}, ${this.#now()})
+        ON CONFLICT (namespace, key) DO NOTHING
+        RETURNING owner, at::float8 AS at`) as ClaimRow[]
+      if (inserted) return { ok: true, claim: { namespace, key, owner: inserted.owner, at: inserted.at } }
+      const held = await this.claimOf(namespace, key)
+      if (held) return held.owner === owner ? { ok: true, claim: held } : { ok: false, conflict: held }
+      // Released in between: claim again.
+      if (attempt >= RACE_RETRIES) throw new Error(`claim ${namespace}/${key} kept changing; try again`)
+    }
+  }
+
+  async release(namespace: string, key: string, owner: string): Promise<boolean> {
+    const sql = await this.#client()
+    const rows = await sql`DELETE FROM hub_claims WHERE namespace = ${namespace} AND key = ${key} AND owner = ${owner} RETURNING owner`
+    return rows.length > 0
+  }
+
+  async claimOf(namespace: string, key: string): Promise<Claim | undefined> {
+    const sql = await this.#client()
+    const [row] = (await sql`SELECT owner, at::float8 AS at FROM hub_claims WHERE namespace = ${namespace} AND key = ${key}`) as ClaimRow[]
+    return row && { namespace, key, owner: row.owner, at: row.at }
+  }
+
+  /** Closes the connection pool (a later call opens a new one). */
+  /** Readiness: SELECT 1 (after the schema check; rejects when the database does not answer, never naming the url). */
+  async ping(): Promise<void> {
+    const sql = await this.#client()
+    await sql`SELECT 1`
+  }
+
+  async close(): Promise<void> {
+    const sql = this.#sql
+    this.#sql = undefined
+    this.#ready = undefined
+    await sql?.close()
+  }
+
+  async #version(sql: SQL, userID: string, collection: string, key: string): Promise<number> {
+    const [row] = (await sql`
+      SELECT version FROM hub_state WHERE user_id = ${userID} AND collection = ${collection} AND key = ${key}`) as { version: number }[]
+    return row?.version ?? 0
+  }
+
+  /** The pool, created on first use, once the schema is current; a failed check is retried by the next call. */
+  async #client(): Promise<SQL> {
+    const sql = (this.#sql ??= new SQL(this.#url, {
+      max: this.#options.max ?? 10,
+      ...(this.#options.connectionTimeoutSeconds !== undefined ? { connectionTimeout: this.#options.connectionTimeoutSeconds } : {}),
+    }))
+    this.#ready ??= this.#checkSchema(sql).catch((error: unknown) => {
+      this.#ready = undefined
+      throw error
+    })
+    await this.#ready
+    return sql
+  }
+
+  async #checkSchema(sql: SQL): Promise<void> {
+    const version = this.#options.migrate ? (await migrate(sql)).version : await schemaVersion(sql)
+    if (version < SCHEMA_VERSION) throw new SchemaOutdatedError(version, SCHEMA_VERSION)
+  }
+}

package/src/central/backend/types.ts

@@ -0,0 +1,244 @@
+// Backend interfaces for state the hub shares between processes (design §9). The single-process hub uses the
+// in-memory implementations (./memory-*); a cluster swaps in Postgres / Valkey ones behind the same contracts.
+// Everything is async so the networked implementations fit. Only new code uses these: existing state (Store,
+// the live-stream EventLog, the Registry) stays where it is.
+
+/** Milliseconds since the epoch (injectable for tests). */
+export type Clock = () => number
+
+/** Timer functions (injectable for tests); the same shape as the Registry's. */
+export interface Timers {
+  set(fn: () => void, ms: number): unknown
+  clear(handle: unknown): void
+}
+
+/** Values the backends store or carry: JSON-compatible data (implementations may serialize them). */
+export type Data = unknown
+
+// ---- StateStore -------------------------------------------------------------------------------------------
+
+/** A stored value and its version (1 for the first write, +1 for every later one). */
+export interface Versioned<T = Data> {
+  readonly value: T
+  readonly version: number
+}
+
+export interface Entry<T = Data> extends Versioned<T> {
+  readonly key: string
+}
+
+/** Optimistic concurrency: `ifVersion` is the version the caller read (0: the key must not exist yet). */
+export interface WriteOptions {
+  readonly ifVersion?: number
+}
+
+/** A write's outcome; on a version mismatch, the version the key has now (0: it does not exist). */
+export type WriteResult = { readonly ok: true; readonly version: number } | { readonly ok: false; readonly version: number }
+
+/** Who holds a unique name (an @name, an exclusive role) in a namespace. */
+export interface Claim {
+  readonly namespace: string
+  readonly key: string
+  readonly owner: string
+  readonly at: number
+}
+
+/** A claim's outcome: the claim, or (conflict) the claim someone else already holds. */
+export type ClaimResult = { readonly ok: true; readonly claim: Claim } | { readonly ok: false; readonly conflict: Claim }
+
+/**
+ * Durable agent data, per user and collection, with optimistic versions; plus unique claims (a database unique
+ * constraint in a cluster).
+ */
+export interface StateStore {
+  get<T = Data>(userID: string, collection: string, key: string): Promise<Versioned<T> | undefined>
+  put<T = Data>(userID: string, collection: string, key: string, value: T, options?: WriteOptions): Promise<WriteResult>
+  /** Removes a key; `ok: false` on a version mismatch. Removing a missing key (without ifVersion) is ok. */
+  delete(userID: string, collection: string, key: string, options?: WriteOptions): Promise<WriteResult>
+  /** The user's entries in a collection, by key. */
+  list<T = Data>(userID: string, collection: string): Promise<Entry<T>[]>
+  /** Claims `key` in `namespace` for `owner`; claiming again for the same owner is ok (the original claim). */
+  claim(namespace: string, key: string, owner: string): Promise<ClaimResult>
+  /** Gives a claim up; false when `owner` does not hold it. */
+  release(namespace: string, key: string, owner: string): Promise<boolean>
+  claimOf(namespace: string, key: string): Promise<Claim | undefined>
+  /** Makes buffered writes durable (the hub calls it on stop); stores that write through omit it. */
+  flush?(): Promise<void>
+  /** Readiness (/readyz): rejects when the database does not answer. In-process stores omit it. */
+  ping?(): Promise<void>
+}
+
+// ---- Bus --------------------------------------------------------------------------------------------------
+
+export type Unsubscribe = () => Promise<void>
+export type BusHandler = (message: Data, topic: string) => void | Promise<void>
+export type BusResponder = (message: Data, topic: string) => Data | Promise<Data>
+
+export interface RequestOptions {
+  readonly timeoutMs: number
+}
+
+/**
+ * Cross-process messages: fire-and-forget publish/subscribe, and request/reply (RPC to the process holding a
+ * connection). Delivery is at most once; a subscriber's failure never reaches the publisher.
+ */
+export interface Bus {
+  /** Sends a message to the topic's current subscribers; resolves with how many there were. */
+  publish(topic: string, message: Data): Promise<number>
+  subscribe(topic: string, handler: BusHandler): Promise<Unsubscribe>
+  /** Answers requests on a topic (one responder per topic). */
+  serve(topic: string, responder: BusResponder): Promise<Unsubscribe>
+  /**
+   * Asks the topic's responder; rejects with BusNoResponderError when there is none, BusTimeoutError after
+   * `timeoutMs`, or BusRemoteError when the responder throws.
+   */
+  request<T = Data>(topic: string, message: Data, options: RequestOptions): Promise<T>
+}
+
+export class BusTimeoutError extends Error {
+  constructor(readonly topic: string, readonly timeoutMs: number) {
+    super(`no reply on ${topic} within ${timeoutMs} ms`)
+    this.name = "BusTimeoutError"
+  }
+}
+
+export class BusNoResponderError extends Error {
+  constructor(readonly topic: string) {
+    super(`no responder on ${topic}`)
+    this.name = "BusNoResponderError"
+  }
+}
+
+export class BusRemoteError extends Error {
+  constructor(readonly topic: string, message: string) {
+    super(message)
+    this.name = "BusRemoteError"
+  }
+}
+
+// ---- EventLog ---------------------------------------------------------------------------------------------
+
+export type EventMessage = { type: string; [key: string]: unknown }
+
+export interface LogEvent {
+  readonly id: string
+  readonly message: EventMessage
+  /** Not for this device (the one that made the change). */
+  readonly exceptDevice?: string
+  readonly at: number
+}
+
+/** The events after an id, or `resync` when the log cannot cover the gap (the client reloads). */
+export type SinceResult = { readonly events: LogEvent[] } | { readonly resync: true }
+
+/** Per-user replay of the live stream, bounded by count and age (a Redis Stream in a cluster). */
+export interface EventLog {
+  append(userID: string, message: EventMessage, options?: { readonly exceptDevice?: string }): Promise<string>
+  /** The id of the user's latest event; a client holding it is covered until events are dropped. */
+  latest(userID: string): Promise<string>
+  since(userID: string, lastID: string): Promise<SinceResult>
+}
+
+// ---- Counters / Locks -------------------------------------------------------------------------------------
+
+/** Fixed-window counters (rate limits, budgets): INCR + PEXPIRE NX in a cluster. */
+export interface Counters {
+  /** Adds one and returns the count; the first increment of a window starts its `ttlMs`. */
+  incr(key: string, ttlMs: number): Promise<number>
+  /** The current count (0 when unset or expired). */
+  get(key: string): Promise<number>
+}
+
+/** A held lock. `fence` grows with every new acquisition of a key (fencing token). */
+export interface Lease {
+  readonly key: string
+  readonly owner: string
+  readonly fence: number
+  readonly expiresAt: number
+}
+
+/** Expiring exclusive leases (SET NX PX in a cluster). */
+export interface Locks {
+  /** Takes the lock, or undefined while someone else holds it; the holder acquiring again renews. */
+  acquire(key: string, owner: string, ttlMs: number): Promise<Lease | undefined>
+  /** Extends the owner's lease; undefined when it no longer holds the lock (expired or taken). */
+  renew(key: string, owner: string, ttlMs: number): Promise<Lease | undefined>
+  /** Releases the owner's lease; false when it does not hold it. */
+  release(key: string, owner: string): Promise<boolean>
+  holder(key: string): Promise<Lease | undefined>
+}
+
+// ---- Kv ---------------------------------------------------------------------------------------------------
+
+/** `set` options: `px` expires the key after that many milliseconds; `nx` writes only when the key is absent. */
+export interface KvSetOptions {
+  readonly px?: number
+  readonly nx?: boolean
+}
+
+/**
+ * Short-lived shared strings (pairing and sign-in codes, OIDC state, directory entries): SET [PX] [NX], GET,
+ * GETDEL and DEL in a cluster. Values are strings; callers encode structured data themselves.
+ */
+export interface Kv {
+  /** Writes the value (dropping any earlier expiry unless `px` is given); false when `nx` and the key exists. */
+  set(key: string, value: string, options?: KvSetOptions): Promise<boolean>
+  get(key: string): Promise<string | undefined>
+  /** Reads and removes the key in one step (a one-time code is redeemed once). */
+  getdel(key: string): Promise<string | undefined>
+  /** Removes the key; true when it existed. */
+  del(key: string): Promise<boolean>
+  /** Readiness (/readyz): rejects when the server does not answer. In-process stores omit it. */
+  ping?(): Promise<void>
+}
+
+// ---- Catalog ----------------------------------------------------------------------------------------------
+
+export type CatalogValue = Record<string, unknown>
+
+/** What one connection reports about a session. */
+export interface CatalogEntry<T extends CatalogValue = CatalogValue> {
+  readonly sessionID: string
+  readonly connID: string
+  readonly value: T
+  readonly at: number
+}
+
+/** A session as all its connections report it, merged. */
+export interface CatalogSession<T extends CatalogValue = CatalogValue> {
+  readonly sessionID: string
+  readonly value: T
+  /** The connections reporting it, oldest report first. */
+  readonly connIDs: string[]
+  /** When the latest report came. */
+  readonly at: number
+}
+
+/** Shared session state per user, keyed by (sessionID, connID) and merged on read (a Redis hash per user). */
+export interface Catalog {
+  /** Records a connection's report; `ttlMs` lets reports of a dead process expire. */
+  set(userID: string, sessionID: string, connID: string, value: CatalogValue, options?: { readonly ttlMs?: number }): Promise<void>
+  /** Removes one connection's report of a session, or (no connID) every report of it. */
+  delete(userID: string, sessionID: string, connID?: string): Promise<void>
+  /** Removes everything a connection reported (it went away). */
+  deleteConn(userID: string, connID: string): Promise<void>
+  get(userID: string, sessionID: string): Promise<CatalogSession | undefined>
+  /** The user's sessions, merged, by session id. */
+  list(userID: string): Promise<CatalogSession[]>
+  /** The raw reports of the user (unmerged). */
+  entries(userID: string): Promise<CatalogEntry[]>
+}
+
+// ---- Bundle -----------------------------------------------------------------------------------------------
+
+export interface Backends {
+  readonly state: StateStore
+  readonly bus: Bus
+  readonly events: EventLog
+  readonly counters: Counters
+  readonly locks: Locks
+  readonly catalog: Catalog
+  readonly kv: Kv
+  /** Closes the connections a networked bundle opened (cluster mode); the hub calls it on stop. */
+  close?(): Promise<void>
+}