airaknit 1.1.2-rc.9

package/src/server/nats-streams.test.ts

@@ -0,0 +1,112 @@
+import { afterEach, describe, test, expect } from "bun:test"
+import { NatsServer } from "@lagz0ne/nats-embedded"
+import { connect, type NatsConnection } from "@nats-io/transport-node"
+import { jetstreamManager } from "@nats-io/jetstream"
+import { Kvm } from "@nats-io/kv"
+import {
+  ensureTerminalEventsStream,
+  TERMINAL_EVENTS_STREAM,
+} from "./nats-streams"
+import { KV_BUCKET, snapshotKvKey } from "../shared/nats-subjects"
+
+let server: NatsServer | null = null
+let nc: NatsConnection | null = null
+
+afterEach(async () => {
+  if (nc) {
+    await nc.drain()
+    nc = null
+  }
+  if (server) {
+    await server.stop()
+    server = null
+  }
+})
+
+describe("nats-streams", () => {
+  test("ensureTerminalEventsStream creates the stream", async () => {
+    server = await NatsServer.start({ jetstream: true })
+    nc = await connect({ servers: server.url })
+
+    await ensureTerminalEventsStream(nc)
+
+    const jsm = await jetstreamManager(nc)
+    const info = await jsm.streams.info(TERMINAL_EVENTS_STREAM)
+    expect(info.config.name).toBe(TERMINAL_EVENTS_STREAM)
+    expect(info.config.subjects).toContain("runtime.evt.terminal.>")
+    expect(info.config.storage).toBe("memory")
+  })
+
+  test("ensureTerminalEventsStream is idempotent", async () => {
+    server = await NatsServer.start({ jetstream: true })
+    nc = await connect({ servers: server.url })
+
+    await ensureTerminalEventsStream(nc)
+    await ensureTerminalEventsStream(nc)
+
+    const jsm = await jetstreamManager(nc)
+    const info = await jsm.streams.info(TERMINAL_EVENTS_STREAM)
+    expect(info.config.name).toBe(TERMINAL_EVENTS_STREAM)
+  })
+
+  test("stream retains published terminal events", async () => {
+    server = await NatsServer.start({ jetstream: true })
+    nc = await connect({ servers: server.url })
+
+    await ensureTerminalEventsStream(nc)
+
+    const jsm = await jetstreamManager(nc)
+    const encoder = new TextEncoder()
+
+    // Publish a terminal event
+    const { jetstream } = await import("@nats-io/jetstream")
+    const js = jetstream(nc)
+    await js.publish(
+      "runtime.evt.terminal.term-1",
+      encoder.encode(JSON.stringify({ type: "terminal.output", terminalId: "term-1", data: "hello" }))
+    )
+
+    const info = await jsm.streams.info(TERMINAL_EVENTS_STREAM)
+    expect(info.state.messages).toBe(1)
+  })
+})
+
+describe("KV snapshot bucket", () => {
+  test("can create and read from runtime_snapshots bucket", async () => {
+    server = await NatsServer.start({ jetstream: true })
+    nc = await connect({ servers: server.url })
+
+    const kvm = new Kvm(nc)
+    const kv = await kvm.create(KV_BUCKET)
+    const encoder = new TextEncoder()
+
+    await kv.put("sidebar", encoder.encode(JSON.stringify({ workspaceGroups: [] })))
+    const entry = await kv.get("sidebar")
+    expect(entry).not.toBeNull()
+    expect(entry!.json() as Record<string, unknown>).toEqual({ workspaceGroups: [] })
+  })
+
+  test("kv dedup: identical puts create new revisions", async () => {
+    server = await NatsServer.start({ jetstream: true })
+    nc = await connect({ servers: server.url })
+
+    const kvm = new Kvm(nc)
+    const kv = await kvm.create(KV_BUCKET)
+    const encoder = new TextEncoder()
+    const data = encoder.encode(JSON.stringify({ test: true }))
+
+    const rev1 = await kv.put("test-key", data)
+    const rev2 = await kv.put("test-key", data)
+    // NATS KV creates new revision even for identical values
+    // (server-side dedup in publisher prevents this)
+    expect(rev2).toBeGreaterThan(rev1)
+  })
+
+  test("snapshotKvKey maps topics correctly", () => {
+    expect(snapshotKvKey({ type: "sidebar" })).toBe("sidebar")
+    expect(snapshotKvKey({ type: "local-workspaces" })).toBe("local-workspaces")
+    expect(snapshotKvKey({ type: "chat", chatId: "abc" })).toBe("chat.abc")
+    expect(snapshotKvKey({ type: "terminal", terminalId: "t1" })).toBe("terminal.t1")
+  })
+})
+

package/src/server/nats-streams.ts

@@ -0,0 +1,129 @@
+import { jetstreamManager, RetentionPolicy, StorageType } from "@nats-io/jetstream"
+import { Kvm } from "@nats-io/kv"
+import type { NatsConnection } from "@nats-io/transport-node"
+import { ALL_TERMINAL_EVENTS, ALL_CHAT_MESSAGE_EVENTS, CHAT_MESSAGE_EVENTS_STREAM_NAME, ALL_WORKSPACE_COORDINATION_EVENTS, WORKSPACE_COORDINATION_EVENTS_STREAM_NAME, ALL_SANDBOX_EVENTS, SANDBOX_EVENTS_STREAM_NAME } from "../shared/nats-subjects"
+import { RUNNER_EVENTS_STREAM, ALL_RUNNER_EVENTS, RUNNER_REGISTRY_BUCKET } from "../shared/runner-protocol"
+import { LOG_PREFIX } from "../shared/branding"
+
+export const TERMINAL_EVENTS_STREAM = "KANNA_TERMINAL_EVENTS"
+export const CHAT_MESSAGE_EVENTS_STREAM = CHAT_MESSAGE_EVENTS_STREAM_NAME
+
+interface StreamConfig {
+  name: string
+  subjects: string[]
+  max_age_ns: number
+  max_msgs: number
+  max_bytes: number
+  storage?: StorageType
+}
+
+const FIVE_MINUTES_NS = 5 * 60 * 1_000_000_000
+const THIRTY_MINUTES_NS = 30 * 60 * 1_000_000_000
+
+async function ensureStream(nc: NatsConnection, config: StreamConfig): Promise<void> {
+  const jsm = await jetstreamManager(nc)
+
+  const streamConfig = {
+    name: config.name,
+    subjects: config.subjects,
+    retention: RetentionPolicy.Limits,
+    storage: config.storage ?? StorageType.Memory,
+    max_age: config.max_age_ns,
+    max_msgs: config.max_msgs,
+    max_bytes: config.max_bytes,
+  }
+
+  try {
+    await jsm.streams.info(config.name)
+    await jsm.streams.update(config.name, streamConfig)
+    console.warn(LOG_PREFIX, `JetStream stream ${config.name} updated`)
+  } catch {
+    // info() throws when stream doesn't exist — safe to create.
+    // Any other error will surface from add().
+    await jsm.streams.add(streamConfig)
+    console.warn(LOG_PREFIX, `JetStream stream ${config.name} created`)
+  }
+}
+
+/** Creates or updates the JetStream stream for terminal events (memory-backed, 5 min / 10K msg retention). */
+export function ensureTerminalEventsStream(nc: NatsConnection): Promise<void> {
+  return ensureStream(nc, {
+    name: TERMINAL_EVENTS_STREAM,
+    subjects: [ALL_TERMINAL_EVENTS],
+    max_age_ns: FIVE_MINUTES_NS,
+    max_msgs: 10_000,
+    max_bytes: 64 * 1024 * 1024,
+  })
+}
+
+/** Creates or updates the JetStream stream for chat message events (memory-backed, 30 min / 50K msg retention). */
+export function ensureChatMessageStream(nc: NatsConnection): Promise<void> {
+  return ensureStream(nc, {
+    name: CHAT_MESSAGE_EVENTS_STREAM,
+    subjects: [ALL_CHAT_MESSAGE_EVENTS],
+    max_age_ns: THIRTY_MINUTES_NS,
+    max_msgs: 50_000,
+    max_bytes: 128 * 1024 * 1024,
+  })
+}
+
+/** Creates or updates the JetStream stream for runner turn events (file-backed, 30 min / 50K msg retention). */
+export function ensureRunnerEventsStream(nc: NatsConnection): Promise<void> {
+  return ensureStream(nc, {
+    name: RUNNER_EVENTS_STREAM,
+    subjects: [ALL_RUNNER_EVENTS],
+    max_age_ns: THIRTY_MINUTES_NS,
+    max_msgs: 50_000,
+    max_bytes: 128 * 1024 * 1024,
+    storage: StorageType.File,
+  })
+}
+
+/** Creates or updates the JetStream stream for project coordination events (file-backed, 24h / 100K msg retention). */
+export function ensureWorkspaceCoordinationStream(nc: NatsConnection): Promise<void> {
+  return ensureStream(nc, {
+    name: WORKSPACE_COORDINATION_EVENTS_STREAM_NAME,
+    subjects: [ALL_WORKSPACE_COORDINATION_EVENTS],
+    max_age_ns: 24 * 60 * 60 * 1_000_000_000,
+    max_msgs: 100_000,
+    max_bytes: 256 * 1024 * 1024,
+    storage: StorageType.File,
+  })
+}
+
+/** Creates or updates the JetStream stream for sandbox events (memory-backed, 5 min / 5K msg retention). */
+export function ensureSandboxEventsStream(nc: NatsConnection): Promise<void> {
+  return ensureStream(nc, {
+    name: SANDBOX_EVENTS_STREAM_NAME,
+    subjects: [ALL_SANDBOX_EVENTS],
+    max_age_ns: FIVE_MINUTES_NS,
+    max_msgs: 5_000,
+    max_bytes: 10 * 1024 * 1024,
+  })
+}
+
+/**
+ * Ensure the runner registry KV bucket exists.
+ *
+ * Called by the server (server-admin connection) at startup so that spawned
+ * runners — whose NATS scope does not include STREAM.CREATE — can open the
+ * bucket immediately without needing to create it themselves.
+ *
+ * Stage D: narrow the runner's $JS.API.> pub allow to the specific subjects
+ * needed for kvm.open + kvStore.put once the exact set is empirically confirmed.
+ */
+export async function ensureRunnerRegistryBucket(nc: NatsConnection): Promise<void> {
+  const kvm = new Kvm(nc)
+  try {
+    // Create with idempotent semantics: if the bucket already exists the
+    // underlying STREAM.CREATE call is treated as an update by nats-server.
+    await kvm.create(RUNNER_REGISTRY_BUCKET, {
+      max_bytes: 1024 * 1024,
+    })
+    console.warn(LOG_PREFIX, `Runner registry KV bucket '${RUNNER_REGISTRY_BUCKET}' ready`)
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err)
+    console.warn(LOG_PREFIX, `Runner registry KV bucket ensure failed: ${message}`)
+    throw err
+  }
+}

package/src/server/oauth-pool/oauth-responders.ts

@@ -0,0 +1,185 @@
+/**
+ * OAuth pool NATS responders.
+ *
+ * Subjects (request/reply under `runtime.cmd.oauth.*`):
+ *   - oauth.list                         -> { ok, settings }
+ *   - oauth.add { label, token, maxConcurrent? }  -> { ok, entry }
+ *   - oauth.remove { id }                -> { ok, removed }
+ *   - oauth.update { id, label?, maxConcurrent? } -> { ok, entry }
+ *   - oauth.setConcurrencyDefault { value } -> { ok }
+ *
+ * Change broadcast: `runtime.evt.oauth.changed` carries snapshot after
+ * mutations so clients can refresh without re-requesting.
+ *
+ * Token values are returned with full secret material — UI only renders
+ * masked previews. Same posture as kanna; tinkaria runs on operator's own
+ * machine.
+ */
+
+import type { NatsConnection, Subscription } from "@nats-io/transport-node"
+import { compressPayload, decompressPayload } from "../../shared/compression"
+import {
+  ALL_OAUTH_COMMANDS,
+  oauthChangedSubject,
+} from "../../shared/nats-subjects"
+import type { ClaudeAuthSettings, OAuthTokenEntry } from "../../shared/types"
+import {
+  OAUTH_TOKEN_LABEL_MAX,
+  OAUTH_TOKEN_MAX_CONCURRENT_MAX,
+  OAUTH_TOKEN_MAX_CONCURRENT_MIN,
+  OAUTH_TOKEN_VALUE_MAX,
+} from "../../shared/types"
+import type { OAuthSettingsStore } from "./oauth-settings-store"
+
+const LOG_PREFIX = "[oauth-pool]"
+const encoder = new TextEncoder()
+const decoder = new TextDecoder()
+
+function encode(data: unknown): Uint8Array {
+  return compressPayload(encoder.encode(JSON.stringify(data)))
+}
+
+async function decode(data: Uint8Array): Promise<unknown> {
+  const raw = await decompressPayload(data)
+  return JSON.parse(decoder.decode(raw))
+}
+
+export interface OAuthResponderDeps {
+  nc: NatsConnection
+  store: OAuthSettingsStore
+}
+
+export interface OAuthResponderHandle {
+  dispose(): void
+}
+
+interface CommandResult {
+  ok: boolean
+  error?: string
+  settings?: ClaudeAuthSettings
+  entry?: OAuthTokenEntry
+  removed?: boolean
+}
+
+export function registerOAuthResponders(deps: OAuthResponderDeps): OAuthResponderHandle {
+  const { nc, store } = deps
+  const sub: Subscription = nc.subscribe(ALL_OAUTH_COMMANDS)
+
+  ;(async () => {
+    for await (const msg of sub) {
+      const subject = msg.subject
+      const type = subject.replace(/^runtime\.cmd\./, "")
+      let payload: Record<string, unknown> = {}
+      try {
+        payload = (await decode(msg.data)) as Record<string, unknown>
+      } catch {
+        msg.respond?.(encode({ ok: false, error: "invalid JSON payload" } satisfies CommandResult))
+        continue
+      }
+      try {
+        const result = await dispatch(type, payload, store)
+        if (result.ok && type !== "oauth.list") {
+          try {
+            nc.publish(oauthChangedSubject(), encode({ settings: store.getSnapshot() }))
+          } catch (err) {
+            console.warn(LOG_PREFIX, "changed publish failed:", err instanceof Error ? err.message : String(err))
+          }
+        }
+        msg.respond?.(encode(result))
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err)
+        console.warn(LOG_PREFIX, `responder error for ${type}: ${message}`)
+        msg.respond?.(encode({ ok: false, error: message } satisfies CommandResult))
+      }
+    }
+  })().catch((err) => {
+    console.warn(LOG_PREFIX, "responder loop terminated:", err instanceof Error ? err.message : String(err))
+  })
+
+  return {
+    dispose() {
+      sub.unsubscribe()
+    },
+  }
+}
+
+async function dispatch(
+  type: string,
+  payload: Record<string, unknown>,
+  store: OAuthSettingsStore,
+): Promise<CommandResult> {
+  switch (type) {
+    case "oauth.list":
+      return { ok: true, settings: store.getSnapshot() }
+
+    case "oauth.add": {
+      const label = requireString(payload, "label").trim()
+      const token = requireString(payload, "token")
+      if (label.length === 0 || label.length > OAUTH_TOKEN_LABEL_MAX) {
+        return { ok: false, error: `label must be 1..${OAUTH_TOKEN_LABEL_MAX} chars` }
+      }
+      if (token.length === 0 || token.length > OAUTH_TOKEN_VALUE_MAX) {
+        return { ok: false, error: `token must be 1..${OAUTH_TOKEN_VALUE_MAX} chars` }
+      }
+      const maxConcurrent = normalizeMaxConcurrent(payload.maxConcurrent)
+      if (maxConcurrent === "invalid") {
+        return { ok: false, error: `maxConcurrent must be in [${OAUTH_TOKEN_MAX_CONCURRENT_MIN}, ${OAUTH_TOKEN_MAX_CONCURRENT_MAX}]` }
+      }
+      const entry = await store.addToken({
+        label,
+        token,
+        ...(maxConcurrent !== undefined ? { maxConcurrent } : {}),
+      })
+      return { ok: true, entry }
+    }
+
+    case "oauth.remove": {
+      const id = requireString(payload, "id")
+      const removed = await store.removeToken(id)
+      return { ok: true, removed }
+    }
+
+    case "oauth.update": {
+      const id = requireString(payload, "id")
+      const patch: { label?: string; maxConcurrent?: number | null } = {}
+      if (typeof payload.label === "string") patch.label = payload.label
+      if (payload.maxConcurrent === null) patch.maxConcurrent = null
+      else if (typeof payload.maxConcurrent === "number") {
+        const v = normalizeMaxConcurrent(payload.maxConcurrent)
+        if (v === "invalid") return { ok: false, error: "maxConcurrent out of range" }
+        if (v !== undefined) patch.maxConcurrent = v
+      }
+      const entry = await store.updateToken(id, patch)
+      if (!entry) return { ok: false, error: `unknown token id: ${id}` }
+      return { ok: true, entry }
+    }
+
+    case "oauth.setConcurrencyDefault": {
+      const value = payload.value
+      if (typeof value !== "number" || value < OAUTH_TOKEN_MAX_CONCURRENT_MIN || value > OAUTH_TOKEN_MAX_CONCURRENT_MAX) {
+        return { ok: false, error: `value must be in [${OAUTH_TOKEN_MAX_CONCURRENT_MIN}, ${OAUTH_TOKEN_MAX_CONCURRENT_MAX}]` }
+      }
+      await store.setConcurrencyDefault(value)
+      return { ok: true }
+    }
+
+    default:
+      return { ok: false, error: `unknown oauth command: ${type}` }
+  }
+}
+
+function requireString(payload: Record<string, unknown>, field: string): string {
+  const value = payload[field]
+  if (typeof value !== "string") {
+    throw new Error(`missing required string field: ${field}`)
+  }
+  return value
+}
+
+function normalizeMaxConcurrent(raw: unknown): number | undefined | "invalid" {
+  if (raw === undefined || raw === null) return undefined
+  if (typeof raw !== "number" || !Number.isFinite(raw)) return "invalid"
+  const rounded = Math.round(raw)
+  if (rounded < OAUTH_TOKEN_MAX_CONCURRENT_MIN || rounded > OAUTH_TOKEN_MAX_CONCURRENT_MAX) return "invalid"
+  return rounded
+}

package/src/server/oauth-pool/oauth-settings-store.ts

@@ -0,0 +1,173 @@
+import { promises as fs } from "fs"
+import path from "path"
+import { homedir } from "os"
+import {
+  CLAUDE_AUTH_DEFAULTS,
+  type ClaudeAuthSettings,
+  type OAuthTokenEntry,
+  type OAuthTokenStatus,
+} from "../../shared/types"
+import type { TokenStatusPatch } from "./oauth-token-pool"
+
+const FILE_NAME = "oauth-tokens.json"
+
+function defaultDir(): string {
+  return path.join(homedir(), ".tinkaria")
+}
+
+function isValidStatus(value: unknown): value is OAuthTokenStatus {
+  return value === "active" || value === "limited" || value === "error" || value === "disabled"
+}
+
+function normalizeEntry(raw: unknown): OAuthTokenEntry | null {
+  if (!raw || typeof raw !== "object") return null
+  const r = raw as Record<string, unknown>
+  if (typeof r.id !== "string" || typeof r.label !== "string" || typeof r.token !== "string") return null
+  const status = isValidStatus(r.status) ? r.status : "active"
+  const out: OAuthTokenEntry = {
+    id: r.id,
+    label: r.label,
+    token: r.token,
+    status,
+    limitedUntil: typeof r.limitedUntil === "number" ? r.limitedUntil : null,
+    lastUsedAt: typeof r.lastUsedAt === "number" ? r.lastUsedAt : null,
+    lastErrorAt: typeof r.lastErrorAt === "number" ? r.lastErrorAt : null,
+    lastErrorMessage: typeof r.lastErrorMessage === "string" ? r.lastErrorMessage : null,
+    addedAt: typeof r.addedAt === "number" ? r.addedAt : Date.now(),
+  }
+  if (typeof r.maxConcurrent === "number" && Number.isFinite(r.maxConcurrent)) {
+    out.maxConcurrent = r.maxConcurrent
+  }
+  return out
+}
+
+function normalizeSettings(raw: unknown): ClaudeAuthSettings {
+  if (!raw || typeof raw !== "object") return { ...CLAUDE_AUTH_DEFAULTS, tokens: [] }
+  const r = raw as Record<string, unknown>
+  const tokensRaw = Array.isArray(r.tokens) ? r.tokens : []
+  const tokens = tokensRaw.map(normalizeEntry).filter((t): t is OAuthTokenEntry => t !== null)
+  const concurrencyDefault = typeof r.concurrencyDefault === "number" && Number.isFinite(r.concurrencyDefault)
+    ? r.concurrencyDefault
+    : CLAUDE_AUTH_DEFAULTS.concurrencyDefault
+  return { tokens, concurrencyDefault }
+}
+
+export class OAuthSettingsStore {
+  private readonly filePath: string
+  private cached: ClaudeAuthSettings = { ...CLAUDE_AUTH_DEFAULTS, tokens: [] }
+  private writeChain: Promise<void> = Promise.resolve()
+  private loaded = false
+
+  constructor(dataDir = defaultDir()) {
+    this.filePath = path.join(dataDir, FILE_NAME)
+  }
+
+  async load(): Promise<void> {
+    try {
+      const raw = await fs.readFile(this.filePath, "utf8")
+      const parsed = JSON.parse(raw)
+      this.cached = normalizeSettings(parsed)
+    } catch (err) {
+      const e = err as NodeJS.ErrnoException
+      if (e.code !== "ENOENT") {
+        console.warn("[oauth-pool] failed to load tokens:", e.message)
+      }
+      this.cached = { ...CLAUDE_AUTH_DEFAULTS, tokens: [] }
+    }
+    this.loaded = true
+  }
+
+  getSnapshot(): ClaudeAuthSettings {
+    return { tokens: [...this.cached.tokens], concurrencyDefault: this.cached.concurrencyDefault }
+  }
+
+  getTokens(): OAuthTokenEntry[] {
+    return [...this.cached.tokens]
+  }
+
+  getConcurrencyDefault(): number {
+    return this.cached.concurrencyDefault
+  }
+
+  async addToken(input: { label: string; token: string; maxConcurrent?: number }): Promise<OAuthTokenEntry> {
+    if (!this.loaded) await this.load()
+    const entry: OAuthTokenEntry = {
+      id: cryptoRandomId(),
+      label: input.label.trim(),
+      token: input.token,
+      status: "active",
+      limitedUntil: null,
+      lastUsedAt: null,
+      lastErrorAt: null,
+      lastErrorMessage: null,
+      addedAt: Date.now(),
+    }
+    if (typeof input.maxConcurrent === "number") entry.maxConcurrent = input.maxConcurrent
+    this.cached = { ...this.cached, tokens: [...this.cached.tokens, entry] }
+    await this.persist()
+    return entry
+  }
+
+  async removeToken(id: string): Promise<boolean> {
+    if (!this.loaded) await this.load()
+    const next = this.cached.tokens.filter((t) => t.id !== id)
+    if (next.length === this.cached.tokens.length) return false
+    this.cached = { ...this.cached, tokens: next }
+    await this.persist()
+    return true
+  }
+
+  async updateToken(id: string, patch: { label?: string; maxConcurrent?: number | null }): Promise<OAuthTokenEntry | null> {
+    if (!this.loaded) await this.load()
+    let updated: OAuthTokenEntry | null = null
+    const next = this.cached.tokens.map((t) => {
+      if (t.id !== id) return t
+      const merged: OAuthTokenEntry = { ...t }
+      if (typeof patch.label === "string") merged.label = patch.label.trim()
+      if (patch.maxConcurrent === null) delete merged.maxConcurrent
+      else if (typeof patch.maxConcurrent === "number") merged.maxConcurrent = patch.maxConcurrent
+      updated = merged
+      return merged
+    })
+    if (!updated) return null
+    this.cached = { ...this.cached, tokens: next }
+    await this.persist()
+    return updated
+  }
+
+  async setConcurrencyDefault(value: number): Promise<void> {
+    if (!this.loaded) await this.load()
+    this.cached = { ...this.cached, concurrencyDefault: value }
+    await this.persist()
+  }
+
+  /** Used by OAuthTokenPool writeStatus callback. Persists asynchronously. */
+  mutateTokenStatus(id: string, patch: TokenStatusPatch): void {
+    const next = this.cached.tokens.map((t) => {
+      if (t.id !== id) return t
+      return { ...t, ...patch }
+    })
+    this.cached = { ...this.cached, tokens: next }
+    this.writeChain = this.writeChain.then(() => this.writeFile()).catch((err) => {
+      console.warn("[oauth-pool] status write failed:", err instanceof Error ? err.message : String(err))
+    })
+  }
+
+  private async persist(): Promise<void> {
+    this.writeChain = this.writeChain.then(() => this.writeFile())
+    await this.writeChain
+  }
+
+  private async writeFile(): Promise<void> {
+    await fs.mkdir(path.dirname(this.filePath), { recursive: true })
+    const tmp = `${this.filePath}.tmp`
+    await fs.writeFile(tmp, JSON.stringify(this.cached, null, 2), "utf8")
+    await fs.rename(tmp, this.filePath)
+  }
+}
+
+function cryptoRandomId(): string {
+  const arr = new Uint8Array(16)
+  crypto.getRandomValues(arr)
+  return Array.from(arr, (b) => b.toString(16).padStart(2, "0")).join("")
+}