@huynle/hub 0.8.2 → 0.8.3

package/src/central/recording/index.ts

@@ -0,0 +1,658 @@
+// REC-01 voice & Concierge recording mode, server half (docs/plans/2026-11-05-voice-recording-contract.md,
+// docs/voice-recording.md). The RecordingService owns the setting, the recordings (records, index, blobs under the
+// `rec~<userID>` tenant), console and hub events, audio, export, delete and the retention sweep. The hub wires its
+// routes (user-only console routes), the voice route hooks, the registry and Concierge taps and the leader.
+//
+// Rules kept everywhere: a recording belongs to one user, one session and one device; every lookup is by
+// (user.id, id) and anything else answers 404 Not found; appends need the recording's own device; hub taps record
+// only while a recording is active for that session, only into the session owner's recordings, and never change
+// what the voice path answers (failures are logged without content or IDs).
+import { randomBytes } from "node:crypto"
+import {
+  RECORDING_AUDIO_TYPE,
+  RECORDING_HEADER,
+  RECORDING_LIMITS,
+  RECORDING_REF_HEADER,
+  RECORDING_SEGMENT_HEADER,
+  type HubEventKind,
+  type RecordingAudioResult,
+  type RecordingEndReason,
+  type RecordingKind,
+  type RecordingSettings,
+  type RecordingUsage,
+} from "../../protocol"
+import { type BlobStore, BlobQuotaError } from "../artifacts/blob-store"
+import type { Decision } from "../agent/decisions"
+import { partyKey } from "../agent/envelope"
+import type { Bus, Clock, StateStore } from "../backend/types"
+import { redactCredentials } from "../profiles/content"
+import type { ConciergeCallFields } from "./concierge-taps"
+import { HubEventWriter, ingestConsole, PAGE_QUOTA_BYTES } from "./ingest"
+import { RecordingRetention } from "./retention"
+import { RecordingSettingsStore } from "./settings"
+import {
+  type AudioEntry,
+  audioKey,
+  ended,
+  isSegmentNumber,
+  newRecord,
+  newRecordingID,
+  type RecordingRecord,
+  RecordingStore,
+  type SpeechFacts,
+  summaryOf,
+} from "./store"
+import { parseTtsRef, RegistryTaps } from "./taps"
+
+const L = RECORDING_LIMITS
+export const RECORDINGS_TOPIC = "recordings.changed"
+/** How long the per-pod active index is trusted without a bus refresh. */
+export const ACTIVE_TTL_MS = 30_000
+/** The grace after a hub-initiated conversation_off end during which the console's last batches are accepted. */
+export const END_GRACE_MS = 10_000
+/** /api/transcribe bodies up to this size are stored before answering (so a failure can be retried with PUT). */
+export const SYNC_AUDIO_BYTES = 512 * 1024
+/** Exports per user at once. */
+export const EXPORTS_PER_USER = 2
+
+/** A console SSE message (IDs, state and counts only). */
+export type RecordingMessage = { type: "recording"; [key: string]: unknown }
+
+export interface RecordingServiceOptions {
+  readonly state: StateStore
+  readonly blobs: BlobStore
+  readonly bus?: Bus
+  readonly now?: Clock
+  /** The cluster pod (page keys and hub event IDs get a per-process tag after it). */
+  readonly podID?: string
+  readonly version?: string
+  /** The session is the user's (registry.owns). */
+  readonly owns: (userID: string, sessionID: string) => boolean
+  readonly sessionTitle: (sessionID: string) => string | undefined
+  /** The session is in conversation mode (an idle recording of it is not ended). */
+  readonly conversation: (sessionID: string) => boolean
+  readonly isConcierge: (userID: string, sessionID: string) => Promise<boolean>
+  /** STT/TTS provider facts of the user (no keys, no base URLs). */
+  readonly speech: (userID: string) => SpeechFacts
+  /** SSE to the user's devices (except one). */
+  readonly notify: (userID: string, message: RecordingMessage, exceptDevice?: string) => void
+  /** Hub audit (no content). */
+  readonly audit: (entry: { actor: string; action: string; target?: string; detail?: string }) => Promise<void>
+  readonly users: () => Promise<readonly string[]>
+  readonly log?: (message: string) => void
+  readonly sweepMs?: number
+  readonly hubFlushMs?: number
+}
+
+interface ActiveRef {
+  readonly id: string
+  readonly sessionID: string
+  readonly kind: RecordingKind
+  readonly deviceID: string
+}
+
+export type AudioOutcome = { readonly kind: "stored"; readonly entry: AudioEntry; readonly fresh: boolean } | { readonly kind: "cap" } | { readonly kind: "gone" } | { readonly kind: "failed"; readonly cause: unknown }
+
+export interface TranscribeTap {
+  /** The answer's x-hub-recording-audio after STT answered (the write of a small body is done by then). */
+  finish(text: string, providerMs: number): Promise<RecordingAudioResult>
+}
+
+export interface SpeakTap {
+  /** Wraps the TTS answer: tts.synth {ref, chars, firstByteMs, ms} is recorded when it ends. */
+  wrap<T extends Uint8Array | ReadableStream<Uint8Array>>(audio: T): T
+}
+
+export class RecordingService {
+  readonly store: RecordingStore
+  readonly settings: RecordingSettingsStore
+  readonly retention: RecordingRetention
+  /** The registry's recording tap (set on Registry.recordingTap). */
+  readonly registryTap: RegistryTaps
+  private readonly writer: HubEventWriter
+  private readonly now: Clock
+  private readonly podTag: string
+  private readonly active = new Map<string, { at: number; refs: ActiveRef[] }>()
+  private readonly tails = new Map<string, Promise<void>>()
+  private readonly exports = new Map<string, number>()
+  private readonly background = new Set<Promise<unknown>>()
+  private readonly opened = new Set<string>()
+  private unsubscribe?: () => Promise<void>
+
+  constructor(private readonly options: RecordingServiceOptions) {
+    this.now = options.now ?? Date.now
+    // Unique per process: a restarted pod never reuses another's page keys.
+    this.podTag = `${(options.podID ?? "hub").replace(/[^A-Za-z0-9]/g, "").slice(0, 12) || "hub"}${randomBytes(3).toString("hex")}`
+    this.store = new RecordingStore(options.state, options.blobs, this.now)
+    this.settings = new RecordingSettingsStore(options.state, this.now)
+    this.writer = new HubEventWriter({
+      store: this.store,
+      now: this.now,
+      podTag: this.podTag,
+      ...(options.hubFlushMs !== undefined ? { flushMs: options.hubFlushMs } : {}),
+      failed: (cause) => this.log(`[hub] recording hub events not written: ${(cause as Error).message}`),
+      overLimit: (userID, id, scope) =>
+        void (async () => {
+          const record = await this.store.visible(userID, id)
+          if (record) await this.capReached(userID, record, "events", scope, scope === "user" ? PAGE_QUOTA_BYTES : L.eventsPerRecording)
+          await this.endByHub(userID, id, "limit")
+        })().catch(() => undefined),
+    })
+    this.retention = new RecordingRetention({ users: options.users, sweepUser: (userID) => this.sweepUser(userID), ...(options.sweepMs !== undefined ? { sweepMs: options.sweepMs } : {}), log: (m) => this.log(m) })
+    this.registryTap = new RegistryTaps({ hub: (userID, sessionID, kind, fields) => this.hub(userID, sessionID, kind, fields), mayRecord: (userID) => this.mayRecord(userID) })
+    if (options.bus) {
+      options.bus
+        .subscribe(RECORDINGS_TOPIC, (message) => {
+          const userID = (message as { userID?: unknown } | undefined)?.userID
+          if (typeof userID === "string") this.active.delete(userID)
+        })
+        .then((off) => (this.unsubscribe = off))
+        .catch((cause) => this.log(`[hub] recordings bus subscription failed: ${(cause as Error).message}`))
+    }
+  }
+
+  private log(message: string): void {
+    ;(this.options.log ?? console.error)(message)
+  }
+
+  /** Tracks a background promise (settled() waits for them). */
+  private track<T>(promise: Promise<T>): Promise<T> {
+    this.background.add(promise)
+    void promise.finally(() => this.background.delete(promise)).catch(() => undefined)
+    return promise
+  }
+
+  // ---- the active index ------------------------------------------------------------------------------------
+
+  /** The user's active recordings (per pod, refreshed by the bus and after ACTIVE_TTL_MS). */
+  private async activeOf(userID: string): Promise<ActiveRef[]> {
+    const cached = this.active.get(userID)
+    if (cached && this.now() - cached.at < ACTIVE_TTL_MS) return cached.refs
+    const refs = (await this.store.list(userID)).filter((r) => r.state === "active").map((r) => ({ id: r.id, sessionID: r.sessionID, kind: r.kind, deviceID: r.deviceID }))
+    this.active.set(userID, { at: this.now(), refs })
+    if (this.active.size > 10_000) this.active.delete(this.active.keys().next().value as string)
+    return refs
+  }
+
+  /** False only when the user surely has no active recording. */
+  mayRecord(userID: string): boolean {
+    const cached = this.active.get(userID)
+    return !(cached && this.now() - cached.at < ACTIVE_TTL_MS && cached.refs.length === 0)
+  }
+
+  /** A recording of the user started or ended: this pod's index and every other pod's are refreshed. */
+  private changed(userID: string, sessionID: string): void {
+    this.active.delete(userID)
+    void this.options.bus?.publish(RECORDINGS_TOPIC, { userID, sessionID }).catch(() => undefined)
+  }
+
+  // ---- hub events ------------------------------------------------------------------------------------------
+
+  /** Records a hub event into every active recording of (user, session), in call order per user. */
+  hub(userID: string, sessionID: string, kind: HubEventKind, fields: Record<string, unknown>, only?: RecordingKind): void {
+    void this.hubNow(userID, sessionID, kind, fields, only)
+  }
+
+  /** hub(), resolving once the event is buffered. */
+  hubNow(userID: string, sessionID: string, kind: HubEventKind, fields: Record<string, unknown>, only?: RecordingKind): Promise<void> {
+    const at = this.now()
+    const add = (refs: readonly ActiveRef[]) => {
+      for (const ref of refs) if (ref.sessionID === sessionID && (only === undefined || ref.kind === only)) this.writer.add(userID, ref.id, kind, fields, at)
+    }
+    const cached = this.active.get(userID)
+    if (!this.tails.has(userID) && cached && this.now() - cached.at < ACTIVE_TTL_MS) {
+      add(cached.refs)
+      return Promise.resolve()
+    }
+    const run = (this.tails.get(userID) ?? Promise.resolve())
+      .then(async () => add(await this.activeOf(userID)))
+      .catch((cause) => this.log(`[hub] recording tap failed: ${(cause as Error).message}`))
+    this.tails.set(userID, run)
+    void run.finally(() => {
+      if (this.tails.get(userID) === run) this.tails.delete(userID)
+    })
+    return run
+  }
+
+  /** Writes every buffered hub event now. */
+  async flush(): Promise<void> {
+    await Promise.all([...this.tails.values()])
+    await this.writer.flush()
+  }
+
+  /** Waits for background work (large audio writes, delete-all) and flushes. */
+  async settled(): Promise<void> {
+    while (this.background.size) await Promise.allSettled([...this.background])
+    await this.flush()
+  }
+
+  async stop(): Promise<void> {
+    this.retention.stop()
+    await this.settled().catch(() => undefined)
+    await this.unsubscribe?.().catch(() => undefined)
+  }
+
+  // ---- settings --------------------------------------------------------------------------------------------
+
+  async usage(userID: string): Promise<RecordingUsage> {
+    const [bytes, records] = await Promise.all([this.store.usage(userID), this.store.list(userID)])
+    return { bytes, recordings: records.filter((r) => r.state !== "deleting").length, capBytes: L.userBytes }
+  }
+
+  async setEnabled(userID: string, deviceID: string, enabled: boolean, expectedRevision: number): Promise<{ ok: true; settings: RecordingSettings } | { ok: false; currentRevision: number }> {
+    const written = await this.settings.set(userID, enabled, expectedRevision)
+    if (!written.ok) return written
+    this.options.notify(userID, { type: "recording", settings: written.settings }, deviceID)
+    if (written.changed) {
+      await this.options.audit({ actor: userID, action: enabled ? "recording.enable" : "recording.disable" })
+      if (!enabled) for (const r of await this.store.list(userID)) if (r.state === "active") await this.endByHub(userID, r.id, "disabled")
+    }
+    return { ok: true, settings: written.settings }
+  }
+
+  // ---- start and end ---------------------------------------------------------------------------------------
+
+  /** Ends a recording (unchanged when it already ended): recording.ended, the pages written, SSE, the index refreshed. */
+  async end(userID: string, id: string, reason: RecordingEndReason, graceUntil?: number): Promise<RecordingRecord | undefined> {
+    const at = this.now()
+    const result = await this.store.update(userID, id, (current) => ended(current, reason, at, graceUntil))
+    if (!result) return undefined
+    if (result.changed) {
+      this.writer.add(userID, id, "recording.ended", { reason }, at)
+      await this.writer.flush(userID, id)
+      this.changed(userID, result.record.sessionID)
+      this.options.notify(userID, { type: "recording", recordingID: id, state: "ended", reason })
+    }
+    return result.record
+  }
+
+  private endByHub(userID: string, id: string, reason: RecordingEndReason, graceUntil?: number) {
+    return this.end(userID, id, reason, graceUntil)
+  }
+
+  async start(userID: string, device: { id: string; name?: string }, input: StartInput): Promise<StartResult> {
+    if (!(await this.settings.get(userID)).enabled) return { kind: "off" }
+    if (!this.options.owns(userID, input.sessionID)) return { kind: "not_found" }
+    const records = await this.store.list(userID)
+    const same = records.find((r) => r.clientID === input.clientID && r.deviceID === device.id && r.state !== "deleting")
+    if (same) return { kind: "existing", record: same }
+    const superseded = records.filter((r) => r.state === "active" && r.deviceID === device.id && r.sessionID === input.sessionID)
+    if (records.filter((r) => r.state === "active").length - superseded.length >= L.activePerUser) return { kind: "rate_limited" }
+    if (records.filter((r) => r.state !== "deleting").length >= L.recordingsStored) return { kind: "limit" }
+    for (const r of superseded) await this.end(userID, r.id, "superseded")
+    const at = this.now()
+    const kind: RecordingKind = (await this.options.isConcierge(userID, input.sessionID).catch(() => false)) ? "concierge" : "voice"
+    const audio = (await this.store.usage(userID)) < L.userBytes
+    const title = this.options.sessionTitle(input.sessionID)?.trim().slice(0, 80)
+    const speech = this.options.speech(userID)
+    const record = newRecord(
+      {
+        id: newRecordingID(),
+        kind,
+        sessionID: input.sessionID,
+        ...(title ? { sessionTitle: title } : {}),
+        deviceID: device.id,
+        ...(device.name ? { deviceName: device.name.slice(0, 80) } : {}),
+        clientID: input.clientID,
+        client: input.client ?? {},
+        anchor: input.anchor ?? { perf: 0, epoch: at },
+        audio,
+        at,
+      },
+      speech,
+    )
+    const created = audio ? record : { ...record, capNoted: ["audio:user"] }
+    if (!(await this.store.create(userID, created))) throw new Error("recording ID collision")
+    // `recordingKind`: the contract's `kind` field would collide with the event envelope's `kind`.
+    this.writer.add(userID, record.id, "recording.started", { recordingKind: kind, sessionID: input.sessionID, deviceID: device.id, ...(speech.stt ? { stt: speech.stt } : {}), ...(speech.tts ? { tts: speech.tts } : {}) }, at)
+    if (!audio) this.writer.add(userID, record.id, "cap.reached", { what: "audio", scope: "user", limit: L.userBytes }, at)
+    this.changed(userID, input.sessionID)
+    return { kind: "created", record: created }
+  }
+
+  // ---- appends ---------------------------------------------------------------------------------------------
+
+  /** The recording when this device may append to it now: active, or ended within its grace. */
+  async appendable(userID: string, deviceID: string, id: string): Promise<{ kind: "ok"; record: RecordingRecord } | { kind: "not_found" } | { kind: "ended"; reason: RecordingEndReason }> {
+    const record = await this.store.visible(userID, id)
+    if (!record || record.deviceID !== deviceID) return { kind: "not_found" }
+    const now = this.now()
+    if (record.state === "active" && now - record.startedAt >= L.maxDurationMs) {
+      const after = await this.end(userID, id, "max_duration")
+      return { kind: "ended", reason: after?.endReason ?? "max_duration" }
+    }
+    if (record.state === "active") return { kind: "ok", record }
+    if (record.graceUntil !== undefined && now <= record.graceUntil) return { kind: "ok", record }
+    return { kind: "ended", reason: record.endReason ?? "stopped" }
+  }
+
+  async appendConsole(userID: string, record: RecordingRecord, events: Parameters<typeof ingestConsole>[3]): Promise<{ kind: "ok"; through: number; audio: boolean } | { kind: "limit" } | { kind: "not_found" }> {
+    const ingested = await ingestConsole(this.store, userID, record, events, this.now)
+    if (ingested.kind === "gone") return { kind: "not_found" }
+    if (ingested.kind === "limit" || ingested.kind === "quota") {
+      if (ingested.kind === "quota") await this.capReached(userID, record, "events", "user", PAGE_QUOTA_BYTES)
+      else await this.capReached(userID, record, "events", "recording", L.eventsPerRecording)
+      await this.end(userID, record.id, "limit")
+      return { kind: "limit" }
+    }
+    return { kind: "ok", through: ingested.record.consoleThrough, audio: ingested.record.audio }
+  }
+
+  /** cap.reached once per (what, scope); an audio cap also turns the recording's audio off (SSE audio:false). */
+  private async capReached(userID: string, record: RecordingRecord, what: "audio" | "events", scope: "user" | "recording", limit: number): Promise<void> {
+    const key = `${what}:${scope}`
+    let note = false
+    let audioOff = false
+    const result = await this.store.update(userID, record.id, (current) => {
+      note = !current.capNoted.includes(key)
+      audioOff = what === "audio" && current.audio
+      if (!note && !audioOff) return undefined
+      return { ...current, capNoted: note ? [...current.capNoted, key] : current.capNoted, ...(what === "audio" ? { audio: false } : {}) }
+    })
+    if (!result?.changed) return
+    if (note) this.writer.add(userID, record.id, "cap.reached", { what, scope, limit })
+    if (audioOff) this.options.notify(userID, { type: "recording", recordingID: record.id, audio: false })
+  }
+
+  /** The user cap for a new segment of `bytes` (cap.reached / audio off when hit); the blob quota enforces it atomically. */
+  private async audioAllowed(userID: string, record: RecordingRecord, bytes: number): Promise<boolean> {
+    if (bytes > L.segmentBytes) return false
+    if (!record.audio) return false
+    if ((await this.store.usage(userID)) + bytes > L.userBytes) {
+      await this.capReached(userID, record, "audio", "user", L.userBytes)
+      return false
+    }
+    return true
+  }
+
+  /**
+   * Reserves a segment's bytes and count in the record (CAS), so parallel writes never pass recordingBytes or
+   * segmentsPerRecording: "ok", "cap" (cap.reached, audio off), or "gone" (deleted meanwhile).
+   */
+  private async reserveAudio(userID: string, record: RecordingRecord, bytes: number): Promise<"ok" | "cap" | "gone"> {
+    let verdict = "gone" as "ok" | "cap" | "over" | "gone"
+    const at = this.now()
+    await this.store.update(userID, record.id, (current) => {
+      if (current.state === "deleting") return void (verdict = "gone")
+      if (!current.audio) return void (verdict = "cap")
+      if (current.segments >= L.segmentsPerRecording || current.bytes + bytes > L.recordingBytes) return void (verdict = "over")
+      verdict = "ok"
+      return { ...current, segments: current.segments + 1, bytes: current.bytes + bytes, lastEventAt: at }
+    })
+    if (verdict === "over") {
+      await this.capReached(userID, record, "audio", "recording", L.recordingBytes)
+      return "cap"
+    }
+    return verdict
+  }
+
+  /** Gives a reservation back (the write failed or lost the first-write race). */
+  private async releaseAudio(userID: string, id: string, bytes: number): Promise<void> {
+    await this.store.update(userID, id, (current) => (current.state === "deleting" ? undefined : { ...current, segments: Math.max(0, current.segments - 1), bytes: Math.max(0, current.bytes - bytes) }))
+  }
+
+  /** Stores a segment's WAV (first write wins); the caps are checked (and reserved) first. */
+  async storeAudio(userID: string, record: RecordingRecord, n: number, audio: Uint8Array, via: AudioEntry["via"], redacted = false): Promise<AudioOutcome> {
+    const existing = await this.store.indexEntry<AudioEntry>(userID, record.id, audioKey(n))
+    if (existing) return { kind: "stored", entry: existing, fresh: false }
+    if (!(await this.audioAllowed(userID, record, audio.length))) return { kind: "cap" }
+    const reserved = await this.reserveAudio(userID, record, audio.length)
+    if (reserved === "cap") return { kind: "cap" }
+    if (reserved === "gone") return { kind: "gone" }
+    let ref
+    try {
+      ref = await this.store.putBlob(userID, audio, RECORDING_AUDIO_TYPE, L.segmentBytes, L.userBytes)
+    } catch (cause) {
+      await this.releaseAudio(userID, record.id, audio.length)
+      if (cause instanceof BlobQuotaError) {
+        await this.capReached(userID, record, "audio", "user", L.userBytes)
+        return { kind: "cap" }
+      }
+      return { kind: "failed", cause }
+    }
+    const at = this.now()
+    const entry: AudioEntry = { hash: ref.hash, bytes: ref.bytes, at, via, ...(redacted ? { redacted: true as const } : {}) }
+    if (!(await this.store.putIndex(userID, record.id, audioKey(n), entry))) {
+      await this.releaseAudio(userID, record.id, audio.length)
+      const first = await this.store.indexEntry<AudioEntry>(userID, record.id, audioKey(n))
+      if (first?.hash !== ref.hash) await this.store.dropIfUnindexed(userID, ref.hash, at)
+      return first ? { kind: "stored", entry: first, fresh: false } : { kind: "failed", cause: new Error("segment index lost") }
+    }
+    // A deletion that ran meanwhile did not see this segment: undo it (delete is real).
+    if (await this.store.undoIfDeleted(userID, record.id, audioKey(n), ref.hash)) return { kind: "gone" }
+    return { kind: "stored", entry, fresh: true }
+  }
+
+  // ---- voice route taps ------------------------------------------------------------------------------------
+
+  /** /api/transcribe with the console's headers: undefined without them (dictation is unchanged). */
+  async transcribeTap(userID: string, deviceID: string, headers: Headers, audio: Uint8Array, format: string): Promise<TranscribeTap | undefined> {
+    const id = headers.get(RECORDING_HEADER)
+    if (id === null) return undefined
+    const off: TranscribeTap = { finish: async () => "off" }
+    const segmentText = headers.get(RECORDING_SEGMENT_HEADER) ?? ""
+    const n = /^\d{1,6}$/.test(segmentText) ? Number(segmentText) : -1
+    let record: RecordingRecord | undefined
+    try {
+      record = await this.store.visible(userID, id)
+    } catch {
+      return off
+    }
+    // Unknown, foreign, ended, another device's, or not a WAV/segment: the headers are ignored (no oracle).
+    if (!record || record.state !== "active" || record.deviceID !== deviceID || !isSegmentNumber(n) || format !== "wav") return off
+    const live = record
+    const at = this.now()
+    this.writer.add(userID, id, "stt.request", { segment: n, bytes: audio.length, format }, at)
+    const model = live.stt?.model
+    return {
+      finish: async (text, providerMs) => {
+        // (USER CHANGE vs the contract text) A transcript matching a secret pattern: the text is scrubbed (the
+        // hub record of stt.result is), the audio kept, and the segment marked redacted.
+        const redacted = redactCredentials(text).kinds.length > 0
+        let result: RecordingAudioResult
+        try {
+          if (!(await this.audioAllowedQuick(userID, live, audio.length))) result = "skipped-cap"
+          else if (audio.length <= SYNC_AUDIO_BYTES) result = this.audioResult(userID, id, n, await this.storeAudio(userID, live, n, audio, "transcribe", redacted))
+          else {
+            result = "stored"
+            void this.track(this.storeAudio(userID, live, n, audio, "transcribe", redacted).then((outcome) => this.audioResult(userID, id, n, outcome)))
+          }
+        } catch (cause) {
+          result = this.audioResult(userID, id, n, { kind: "failed", cause })
+        }
+        this.writer.add(userID, id, "stt.result", { segment: n, text, providerMs, ...(model ? { model } : {}), audio: result })
+        return result
+      },
+    }
+  }
+
+  /** The cap checks of a transcribe body (the store re-checks them). */
+  private async audioAllowedQuick(userID: string, record: RecordingRecord, bytes: number): Promise<boolean> {
+    const current = (await this.store.get(userID, record.id))?.value ?? record
+    return this.audioAllowed(userID, current, bytes)
+  }
+
+  private audioResult(userID: string, id: string, n: number, outcome: AudioOutcome): RecordingAudioResult {
+    if (outcome.kind === "stored") return "stored"
+    if (outcome.kind === "cap") return "skipped-cap"
+    // Deleted meanwhile: like an unknown recording.
+    if (outcome.kind === "gone") return "off"
+    this.log(`[hub] recording audio not stored: ${(outcome.cause as Error)?.message ?? "error"}`)
+    this.writer.add(userID, id, "error", { where: "audio", segment: n, message: (outcome.cause as Error)?.message ?? "write failed" })
+    return "failed"
+  }
+
+  /** /api/speak with x-hub-recording (and x-hub-tts-ref): tts.synth timing; the reply audio is never stored. */
+  async speakTap(userID: string, deviceID: string, headers: Headers, chars: number): Promise<SpeakTap | undefined> {
+    const id = headers.get(RECORDING_HEADER)
+    if (id === null) return undefined
+    const record = await this.store.visible(userID, id).catch(() => undefined)
+    if (!record || record.state !== "active" || record.deviceID !== deviceID) return undefined
+    const ref = parseTtsRef(headers.get(RECORDING_REF_HEADER))
+    const started = this.now()
+    const done = (firstByteMs: number | undefined) => this.writer.add(userID, id, "tts.synth", { ...(ref ? { ref } : {}), chars, ...(firstByteMs !== undefined ? { firstByteMs } : {}), ms: this.now() - started })
+    return {
+      wrap: <T extends Uint8Array | ReadableStream<Uint8Array>>(audio: T): T => {
+        if (audio instanceof Uint8Array) {
+          const ms = this.now() - started
+          done(ms)
+          return audio
+        }
+        let first: number | undefined
+        const timed = (audio as ReadableStream<Uint8Array>).pipeThrough(
+          new TransformStream<Uint8Array, Uint8Array>({
+            transform: (chunk, controller) => {
+              first ??= this.now() - started
+              controller.enqueue(chunk)
+            },
+            flush: () => done(first),
+          }),
+        )
+        return timed as T
+      },
+    }
+  }
+
+  /** POST …/conversation: the event, and (off) the session's recordings end with a grace for the last batches. */
+  async conversationChanged(userID: string, sessionID: string, on: boolean): Promise<void> {
+    await this.hubNow(userID, sessionID, "conversation", { on })
+    if (on) return
+    for (const ref of await this.activeOf(userID)) {
+      if (ref.sessionID === sessionID) await this.end(userID, ref.id, "conversation_off", this.now() + END_GRACE_MS)
+    }
+  }
+
+  /** A session was deleted: its recordings end. */
+  async sessionDeleted(userID: string, sessionID: string): Promise<void> {
+    for (const ref of await this.activeOf(userID)) if (ref.sessionID === sessionID) await this.end(userID, ref.id, "session_deleted")
+  }
+
+  /** Decisions: opened (asked by the recorded session) and answered (with via). */
+  decisionChanged(userID: string, decision: Decision): void {
+    const from = decision.from
+    if (from.kind !== "session") return
+    const sessionID = from.sessionID
+    if (decision.state === "open" && !this.opened.has(decision.id)) {
+      this.opened.add(decision.id)
+      if (this.opened.size > 2000) this.opened.delete(this.opened.values().next().value as string)
+      this.hub(userID, sessionID, "decision.opened", { decisionID: decision.id, from: partyKey(from), tier: decision.tier, urgency: decision.urgency, options: decision.options.map((o) => o.id), text: decision.question })
+    } else if (decision.state === "answered" && decision.answer?.answeredBy === "user") {
+      this.hub(userID, sessionID, "decision.answered", { decisionID: decision.id, ...(decision.answer.option !== undefined ? { option: decision.answer.option } : {}), via: decision.answer.via ?? "tap" })
+    }
+  }
+
+  /** concierge.tool: an agent call of a recorded Concierge session (no body, no response). */
+  conciergeCall(userID: string, sessionID: string, fields: ConciergeCallFields): void {
+    if (!this.mayRecord(userID)) return
+    this.hub(userID, sessionID, "concierge.tool", { ...fields }, "concierge")
+  }
+
+  /** wake.arrived: the notifier's send to the recorded Concierge session succeeded. */
+  wake(userID: string, sessionID: string, fields: Record<string, unknown>): void {
+    this.hub(userID, sessionID, "wake.arrived", fields, "concierge")
+  }
+
+  // ---- reads -----------------------------------------------------------------------------------------------
+
+  async visible(userID: string, id: string): Promise<RecordingRecord | undefined> {
+    return this.store.visible(userID, id)
+  }
+
+  async list(userID: string): Promise<RecordingRecord[]> {
+    return (await this.store.list(userID)).filter((r) => r.state !== "deleting").sort((a, b) => b.startedAt - a.startedAt || (a.id < b.id ? 1 : -1))
+  }
+
+  /** One export slot of the user, or undefined at EXPORTS_PER_USER; release it when the stream ends. */
+  exportSlot(userID: string): (() => void) | undefined {
+    const running = this.exports.get(userID) ?? 0
+    if (running >= EXPORTS_PER_USER) return undefined
+    this.exports.set(userID, running + 1)
+    let released = false
+    return () => {
+      if (released) return
+      released = true
+      const left = (this.exports.get(userID) ?? 1) - 1
+      if (left <= 0) this.exports.delete(userID)
+      else this.exports.set(userID, left)
+    }
+  }
+
+  // ---- delete ----------------------------------------------------------------------------------------------
+
+  /** Step 1: ends an active recording (stopped), then marks it deleting (invisible to every route from then on). */
+  private async markDeleting(userID: string, id: string): Promise<boolean> {
+    const record = await this.store.visible(userID, id)
+    if (!record) return false
+    if (record.state === "active") await this.end(userID, id, "stopped")
+    await this.writer.flush(userID, id)
+    const at = this.now()
+    await this.store.tombstone(userID, id, at)
+    const result = await this.store.update(userID, id, (current) => (current.state === "deleting" ? undefined : { ...current, state: "deleting", deletingAt: at }))
+    if (!result?.changed) return false
+    this.writer.discard(userID, id)
+    this.options.notify(userID, { type: "recording", recordingID: id, state: "deleted" })
+    return true
+  }
+
+  async deleteOne(userID: string, id: string): Promise<boolean> {
+    if (!(await this.markDeleting(userID, id))) return false
+    await this.store.finishDelete(userID, id)
+    await this.options.audit({ actor: userID, action: "recording.delete", target: id, detail: "1" })
+    return true
+  }
+
+  /** Every recording of the user: marked now, finished in the background (the sweep finishes what a crash left). */
+  async deleteAll(userID: string): Promise<number> {
+    const ids: string[] = []
+    for (const record of await this.store.list(userID)) if (record.state !== "deleting" && (await this.markDeleting(userID, record.id))) ids.push(record.id)
+    await this.options.audit({ actor: userID, action: "recording.delete", target: "all", detail: String(ids.length) })
+    void this.track(
+      (async () => {
+        for (const id of ids) await this.store.finishDelete(userID, id).catch((cause) => this.log(`[hub] recording delete not finished: ${(cause as Error).message}`))
+      })(),
+    )
+    return ids.length
+  }
+
+  // ---- retention -------------------------------------------------------------------------------------------
+
+  /** One user's sweep: finish deletions, delete expired, end idle and over-long active recordings. */
+  async sweepUser(userID: string): Promise<number> {
+    const now = this.now()
+    let expired = 0
+    for (const record of await this.store.list(userID)) {
+      if (record.state === "deleting") {
+        await this.store.finishDelete(userID, record.id)
+        continue
+      }
+      if (record.expiresAt <= now) {
+        if (record.state === "active") await this.end(userID, record.id, "stale")
+        if (await this.markDeleting(userID, record.id)) {
+          await this.store.finishDelete(userID, record.id)
+          expired++
+        }
+        continue
+      }
+      if (record.state !== "active") continue
+      if (now - record.startedAt >= L.maxDurationMs) await this.end(userID, record.id, "max_duration")
+      else if (now - record.lastEventAt >= L.idleEndMs && !this.options.conversation(record.sessionID)) await this.end(userID, record.id, "stale")
+    }
+    // Leftovers of writes that raced a deletion (index keys of gone recordings, unindexed blobs past the grace).
+    await this.store.sweepOrphans(userID)
+    if (expired) await this.options.audit({ actor: "system", action: "recording.purge", detail: `${expired} expired` })
+    return expired
+  }
+}
+
+export interface StartInput {
+  readonly sessionID: string
+  readonly clientID: string
+  readonly anchor?: RecordingRecord["anchor"]
+  readonly client?: RecordingRecord["client"]
+}
+
+export type StartResult =
+  | { readonly kind: "off" | "not_found" | "rate_limited" | "limit" }
+  | { readonly kind: "existing" | "created"; readonly record: RecordingRecord }
+
+export { summaryOf }