@huynle/hub 0.8.1 → 0.8.3

package/src/central/recording/schema.ts

@@ -0,0 +1,232 @@
+// REC-01 recording event schema (docs/plans/2026-11-05-voice-recording-contract.md, Event schema).
+// The console kinds and exactly their fields: a batch with an unknown kind, an unknown field (also inside nested
+// objects), a wrong type or a missing required field is refused whole, naming the event's seq. Every ✂ text field,
+// from either source, is scrubbed (redactCredentials) and then cut at its limit before it is stored.
+import { type ConsoleEvent, type ConsoleEventKind, type HubEventKind, RECORDING_LIMITS, type RecordingEvent } from "../../protocol"
+import { redactCredentials } from "../profiles/content"
+
+/** A field's shape. `text` fields are the ✂ ones: scrubbed and cut at `max`, never refused for length. */
+export type FieldSpec =
+  | { readonly t: "int" | "num" | "bool" | "true" }
+  | { readonly t: "str"; readonly max: number }
+  | { readonly t: "text"; readonly max: number }
+  | { readonly t: "enum"; readonly values: readonly string[] }
+  | { readonly t: "array"; readonly of: FieldSpec; readonly max: number }
+  | { readonly t: "object"; readonly fields: Fields }
+
+/** Field name → spec; a name ending in `?` is optional. */
+export type Fields = Readonly<Record<string, FieldSpec>>
+
+const int: FieldSpec = { t: "int" }
+const num: FieldSpec = { t: "num" }
+const bool: FieldSpec = { t: "bool" }
+const yes: FieldSpec = { t: "true" }
+/** IDs and labels the console echoes (message IDs, inbox IDs, Decision IDs, option IDs). */
+const id: FieldSpec = { t: "str", max: 300 }
+const label: FieldSpec = { t: "str", max: 60 }
+const text = (max: number): FieldSpec => ({ t: "text", max })
+const oneOf = (...values: string[]): FieldSpec => ({ t: "enum", values })
+const list = (of: FieldSpec, max: number): FieldSpec => ({ t: "array", of, max })
+const object = (fields: Fields): FieldSpec => ({ t: "object", fields })
+
+const L = RECORDING_LIMITS
+const ref = object({ messageID: id, ordinal: int, "seq?": int, i: int })
+const AUDIO_RESULTS = ["stored", "skipped-cap", "failed", "off"]
+
+/** The console kinds (REC-02 emits exactly these fields). */
+export const CONSOLE_FIELDS: Readonly<Record<ConsoleEventKind, Fields>> = {
+  state: { state: label },
+  detector: { mode: oneOf("silero", "energy"), "avgMs?": num },
+  "speech.start": { bargeIn: bool },
+  "speech.end": { segment: int, durationMs: num, speechMs: num, forced: bool },
+  "segment.closed": { segment: int, bytes: int, durationMs: num, speechMs: num, forced: bool },
+  "stt.sent": { segment: int, bytes: int },
+  // `text` is optional: a failed request has none (failed names why).
+  "stt.received": { segment: int, "text?": text(L.textChars), "junk?": yes, "empty?": yes, "failed?": text(L.messageChars), "audio?": oneOf(...AUDIO_RESULTS) },
+  "utterance.held": { text: text(L.utteranceChars) },
+  "utterance.merged": { segments: list(int, 1000), pauseMs: num },
+  "utterance.sent": { text: text(L.utteranceChars), segments: list(int, 1000), reason: oneOf("finished", "hold", "max", "command", "typed"), holdMs: num },
+  "utterance.accepted": { inboxID: id },
+  "utterance.failed": { "status?": int, message: text(L.messageChars) },
+  "utterance.command": { command: oneOf("pause", "interrupt"), text: text(L.textChars) },
+  heard: { inboxID: id },
+  // The contract's `seq?` (the say's seq) collides with the envelope's `seq`: a flat event carries only the latter.
+  "say.received": { messageID: id, ordinal: int, chars: int, sentences: int, muted: bool },
+  "tts.sentence.queued": { ref, text: text(L.textChars) },
+  "tts.request": { ref },
+  "tts.first.byte": { ref },
+  "tts.sentence.played": { ref },
+  "tts.sentence.ended": { ref, playedMs: num, "durationMs?": num, completed: bool },
+  "barge.in": {
+    cause: oneOf("speech", "typed", "command", "hush", "pause", "stop"),
+    "playing?": object({ ref, text: text(L.textChars), playedMs: num, "durationMs?": num }),
+    spoken: object({ text: text(L.replyChars), estimated: bool }),
+    unplayed: list(object({ ref, text: text(L.textChars) }), 20),
+    mutedMessages: list(id, 20),
+  },
+  "cue.played": { cue: oneOf("earcon", "phrase"), "name?": label, "text?": text(L.textChars) },
+  mic: { live: bool, "reason?": label },
+  control: { action: oneOf("pause", "resume", "hush", "background", "cues"), "on?": bool },
+  "turn.timing": { "speechEnd?": num, "transcript?": num, "accepted?": num, "firstSay?": num, "firstByte?": num, firstAudio: num },
+  "decision.voice": { decisionID: id, option: id, outcome: oneOf("answered", "refused", "failed") },
+  "clock.sync": { t0: num, t1: num, hubAt: num },
+  error: { where: oneOf("stt", "tts", "send", "mic", "upload", "audio"), message: text(L.messageChars) },
+}
+
+/** The ✂ fields of the hub kinds (the hub writes the rest itself: only text needs scrubbing and cutting). */
+const HUB_TEXT: Partial<Record<HubEventKind, Readonly<Record<string, number>>>> = {
+  "stt.result": { text: L.textChars },
+  "utterance.received": { text: L.utteranceChars },
+  "say.sent": { text: L.textChars },
+  "reply.full": { text: L.replyChars },
+  tool: { summary: L.textChars },
+  "wake.arrived": { text: L.textChars },
+  "decision.opened": { text: L.textChars },
+  error: { message: L.messageChars },
+}
+
+class Invalid extends Error {}
+
+const isRecord = (v: unknown): v is Record<string, unknown> => typeof v === "object" && v !== null && !Array.isArray(v)
+
+function checkValue(spec: FieldSpec, value: unknown, where: string): void {
+  const fail = (what: string): never => {
+    throw new Invalid(`${where} must be ${what}`)
+  }
+  switch (spec.t) {
+    case "int":
+      if (!Number.isSafeInteger(value)) fail("an integer")
+      return
+    case "num":
+      if (typeof value !== "number" || !Number.isFinite(value)) fail("a finite number")
+      return
+    case "bool":
+      if (typeof value !== "boolean") fail("true or false")
+      return
+    case "true":
+      if (value !== true) fail("true")
+      return
+    case "str":
+      if (typeof value !== "string" || value.length > spec.max) fail(`text of at most ${spec.max} characters`)
+      return
+    case "text":
+      if (typeof value !== "string") fail("text")
+      return
+    case "enum":
+      if (typeof value !== "string" || !spec.values.includes(value)) fail(`one of ${spec.values.join(", ")}`)
+      return
+    case "array":
+      if (!Array.isArray(value) || value.length > spec.max) fail(`a list of at most ${spec.max}`)
+      ;(value as unknown[]).forEach((item, i) => checkValue(spec.of, item, `${where}[${i}]`))
+      return
+    case "object":
+      if (!isRecord(value)) fail("an object")
+      checkFields(spec.fields, value as Record<string, unknown>, `${where}.`)
+  }
+}
+
+function checkFields(fields: Fields, value: Record<string, unknown>, prefix: string, skip: ReadonlySet<string> = new Set()): void {
+  const known = new Map(Object.entries(fields).map(([name, spec]) => [name.replace(/\?$/, ""), { spec, optional: name.endsWith("?") }]))
+  for (const key of Object.keys(value)) {
+    if (skip.has(key)) continue
+    if (!known.has(key)) throw new Invalid(`unknown field ${prefix}${/^[A-Za-z0-9_.-]{1,40}$/.test(key) ? key : "?"}`)
+  }
+  for (const [name, { spec, optional }] of known) {
+    if (value[name] === undefined) {
+      if (optional) continue
+      throw new Invalid(`${prefix}${name} is required`)
+    }
+    checkValue(spec, value[name], `${prefix}${name}`)
+  }
+}
+
+const ENVELOPE = new Set(["seq", "t", "kind"])
+
+export type BatchCheck =
+  | { readonly ok: true; readonly events: readonly ConsoleEvent[] }
+  | { readonly ok: false; readonly problem: string; readonly seq?: number; readonly limit?: true }
+
+/** Checks a console batch (`events` of POST …/events): count, envelopes, kinds and their fields. */
+export function checkConsoleBatch(events: unknown): BatchCheck {
+  if (!Array.isArray(events) || events.length === 0) return { ok: false, problem: "Expected {events: [ConsoleEvent, …]} with at least one event" }
+  if (events.length > L.eventsPerBatch) return { ok: false, limit: true, problem: `A batch holds at most ${L.eventsPerBatch} events` }
+  let previous: number | undefined
+  for (const event of events) {
+    const seq = isRecord(event) && Number.isSafeInteger(event.seq) ? (event.seq as number) : undefined
+    try {
+      if (!isRecord(event)) throw new Invalid("an event must be an object")
+      if (seq === undefined || seq < 1) throw new Invalid("seq must be an integer from 1")
+      if (previous !== undefined && seq !== previous + 1) throw new Invalid("seq must increase by 1 within a batch")
+      if (typeof event.t !== "number" || !Number.isFinite(event.t) || event.t < 0) throw new Invalid("t must be a finite number ≥ 0")
+      const fields = typeof event.kind === "string" && Object.hasOwn(CONSOLE_FIELDS, event.kind) ? CONSOLE_FIELDS[event.kind as ConsoleEventKind] : undefined
+      if (!fields) throw new Invalid("unknown kind")
+      checkFields(fields, event, "", ENVELOPE)
+    } catch (cause) {
+      if (!(cause instanceof Invalid)) throw cause
+      return { ok: false, problem: cause.message, ...(seq !== undefined ? { seq } : {}) }
+    }
+    previous = seq
+  }
+  return { ok: true, events: events as ConsoleEvent[] }
+}
+
+/** Scrubs and cuts the text fields of a value by its spec; records the kinds removed and whether anything was cut. */
+function scrubValue(spec: FieldSpec, value: unknown, marks: Marks): unknown {
+  if (spec.t === "text" && typeof value === "string") return scrubText(value, spec.max, marks)
+  if (spec.t === "array" && Array.isArray(value)) return value.map((item) => scrubValue(spec.of, item, marks))
+  if (spec.t === "object" && isRecord(value)) return scrubFields(spec.fields, value, marks)
+  return value
+}
+
+function scrubFields(fields: Fields, value: Record<string, unknown>, marks: Marks): Record<string, unknown> {
+  const out: Record<string, unknown> = {}
+  const specs = new Map(Object.entries(fields).map(([name, spec]) => [name.replace(/\?$/, ""), spec]))
+  for (const [key, item] of Object.entries(value)) {
+    const spec = specs.get(key)
+    out[key] = spec ? scrubValue(spec, item, marks) : item
+  }
+  return out
+}
+
+interface Marks {
+  kinds: string[]
+  truncated: boolean
+}
+
+/** Redacts a text, then cuts it at `max` characters (redacting first: a cut must never leave half a secret). */
+export function scrubText(value: string, max: number, marks: Marks): string {
+  const { text: clean, kinds } = redactCredentials(value)
+  for (const kind of kinds) if (!marks.kinds.includes(kind)) marks.kinds.push(kind)
+  if (clean.length <= max) return clean
+  marks.truncated = true
+  return clean.slice(0, max)
+}
+
+const withMarks = (record: Record<string, unknown>, marks: Marks): RecordingEvent =>
+  ({ ...record, ...(marks.kinds.length ? { redacted: marks.kinds } : {}), ...(marks.truncated ? { truncated: true as const } : {}) }) as RecordingEvent
+
+/** A checked console event as stored: the envelope, the receive time, scrubbed and cut fields. */
+export function consoleRecord(event: ConsoleEvent, at: number): RecordingEvent {
+  const marks: Marks = { kinds: [], truncated: false }
+  const { seq, t, kind, ...rest } = event
+  const fields = scrubFields(CONSOLE_FIELDS[kind], rest, marks)
+  return withMarks({ v: 1, src: "console", seq, t, at, kind, ...fields }, marks)
+}
+
+// Not `seq`: hub events have no envelope seq, and say.sent carries the say's own.
+const HUB_ENVELOPE = ["v", "src", "id", "at", "kind", "ts", "redacted", "truncated"]
+
+/** A hub event as stored: `id` and `at`, its text fields scrubbed and cut. */
+export function hubRecord(kind: HubEventKind, fields: Record<string, unknown>, meta: { readonly id: string; readonly at: number }): RecordingEvent {
+  const marks: Marks = { kinds: [], truncated: false }
+  const limits = HUB_TEXT[kind] ?? {}
+  const out: Record<string, unknown> = {}
+  for (const [key, value] of Object.entries(fields)) {
+    if (value === undefined) continue
+    const max = limits[key]
+    out[key] = max !== undefined && typeof value === "string" ? scrubText(value, max, marks) : value
+  }
+  // The envelope always wins over a field of the same name.
+  for (const key of HUB_ENVELOPE) delete out[key]
+  return withMarks({ v: 1, src: "hub", id: meta.id, at: meta.at, kind, ...out }, marks)
+}

package/src/central/recording/settings.ts

@@ -0,0 +1,35 @@
+// REC-01 recording setting (contract: Setting and indicator): per user, off by default, version-checked by the
+// caller's expectedRevision. StateStore collection `voice-recording-settings`, key `settings`.
+import type { RecordingSettings } from "../../protocol"
+import type { Clock, StateStore } from "../backend/types"
+
+export const SETTINGS_COLLECTION = "voice-recording-settings"
+const KEY = "settings"
+export const DEFAULT_SETTINGS: RecordingSettings = { enabled: false, revision: 0 }
+
+export type SettingsWrite = { readonly ok: true; readonly settings: RecordingSettings; readonly changed: boolean } | { readonly ok: false; readonly currentRevision: number }
+
+export class RecordingSettingsStore {
+  constructor(
+    private readonly state: StateStore,
+    private readonly now: Clock,
+  ) {}
+
+  async get(userID: string): Promise<RecordingSettings> {
+    return (await this.state.get<RecordingSettings>(userID, SETTINGS_COLLECTION, KEY))?.value ?? DEFAULT_SETTINGS
+  }
+
+  /** Sets `enabled` when the stored revision is `expectedRevision`; a stale one answers the current revision. */
+  async set(userID: string, enabled: boolean, expectedRevision: number): Promise<SettingsWrite> {
+    for (let attempt = 0; attempt < 8; attempt++) {
+      const stored = await this.state.get<RecordingSettings>(userID, SETTINGS_COLLECTION, KEY)
+      const current = stored?.value ?? DEFAULT_SETTINGS
+      if (current.revision !== expectedRevision) return { ok: false, currentRevision: current.revision }
+      const next: RecordingSettings = { enabled, revision: current.revision + 1, updatedAt: this.now() }
+      const written = await this.state.put(userID, SETTINGS_COLLECTION, KEY, next, { ifVersion: stored?.version ?? 0 })
+      if (written.ok) return { ok: true, settings: next, changed: current.enabled !== enabled }
+    }
+    const current = await this.get(userID)
+    return { ok: false, currentRevision: current.revision }
+  }
+}

package/src/central/recording/store.ts

@@ -0,0 +1,316 @@
+// REC-01 recording storage (contract: Recordings → Storage). Small records in the StateStore under the real user
+// ID (`voice-recordings`, every update CAS), one index collection per recording (`voice-recording-index:<id>`:
+// console pages c…, hub pages h…, audio segments a…), and the bytes in the BlobStore under the separate tenant
+// `rec~<userID>` (artifact recovery walks only real user IDs, so it never sweeps them; usage() of the tenant is
+// exactly the recording usage). Deletion is real: blobs (unless another recording of the user indexes the hash,
+// with touchedBefore = the deletion start), then the index, then the record.
+import { randomBytes } from "node:crypto"
+import {
+  RECORDING_LIMITS,
+  RECORDING_MEDIA_TYPES,
+  type BlobRef,
+  type RecordingAnchor,
+  type RecordingAudioResult,
+  type RecordingClient,
+  type RecordingEndReason,
+  type RecordingSummary,
+} from "../../protocol"
+import type { BlobBody, BlobStore } from "../artifacts/blob-store"
+import type { Clock, Entry, StateStore, Versioned } from "../backend/types"
+
+export const RECORDINGS = "voice-recordings"
+/** Unindexed rec~ blobs younger than this are left to their writer (a write in flight); older ones are swept. */
+export const ORPHAN_GRACE_MS = 60 * 60_000
+export const indexCollection = (recordingID: string) => `voice-recording-index:${recordingID}`
+/**
+ * Recordings being or recently deleted (key: the ID, value {at}): the sweep empties their index collections again
+ * (a write racing the deletion, another pod's late page), since a StateStore cannot list collections.
+ */
+export const TOMBSTONES = "voice-recording-tombstones"
+/** How long a tombstone is kept after its index was found empty. */
+export const TOMBSTONE_MS = 24 * 60 * 60_000
+/** The BlobStore tenant of a user's recordings (user IDs never contain `~`). */
+export const blobTenant = (userID: string) => `rec~${userID}`
+
+/** Speech provider facts at start (no keys, no base URLs). */
+export interface SpeechFacts {
+  readonly stt?: { readonly provider?: string; readonly model?: string }
+  readonly tts?: { readonly provider?: string; readonly model?: string; readonly voice?: string }
+}
+
+/** A recording as stored: the summary plus internal fields (kept small: ≤ 4 KiB). */
+export interface RecordingRecord extends RecordingSummary, SpeechFacts {
+  readonly clientID: string
+  readonly client: RecordingClient
+  readonly anchor: RecordingAnchor
+  /** Highest contiguous console seq stored. */
+  readonly consoleThrough: number
+  readonly consoleGaps: number
+  readonly hubPages: number
+  readonly pages: number
+  readonly eventBytes: number
+  readonly lastEventAt: number
+  /** `<what>:<scope>` caps already reported (cap.reached once each). */
+  readonly capNoted: readonly string[]
+  readonly skipped: { readonly cap: number; readonly failed: number }
+  /** Appends are still accepted until then (the 10 s grace after a hub-initiated conversation_off end). */
+  readonly graceUntil?: number
+  readonly deletingAt?: number
+}
+
+export interface ConsolePageEntry {
+  readonly hash: string
+  readonly bytes: number
+  readonly first: number
+  readonly last: number
+  readonly at: number
+}
+export interface HubPageEntry {
+  readonly hash: string
+  readonly bytes: number
+  readonly count: number
+  readonly at: number
+}
+export interface AudioEntry {
+  readonly hash: string
+  readonly bytes: number
+  readonly durationMs?: number
+  readonly at: number
+  readonly via: "transcribe" | "put"
+  /** (USER CHANGE) The segment's transcript matched a secret pattern: its text was scrubbed, the audio kept. */
+  readonly redacted?: true
+}
+
+export const consoleKey = (firstSeq: number) => `c${String(firstSeq).padStart(10, "0")}`
+export const hubKey = (podTag: string, n: number) => `h${podTag}-${String(n).padStart(8, "0")}`
+export const audioKey = (n: number) => `a${String(n).padStart(6, "0")}`
+/** Segment numbers that fit the 6-digit index key and file name. */
+export const isSegmentNumber = (n: number) => Number.isSafeInteger(n) && n >= 0 && n <= 999_999
+
+const BASE32 = "abcdefghijklmnopqrstuvwxyz234567"
+/** "rec_" + 20 base32 characters (100 random bits). */
+export function newRecordingID(): string {
+  const bytes = randomBytes(20)
+  let out = ""
+  for (const b of bytes) out += BASE32[b & 31]
+  return `rec_${out}`
+}
+export const isRecordingID = (id: string) => /^rec_[a-z2-7]{20}$/.test(id)
+
+/** The public part of a record. */
+export function summaryOf(r: RecordingRecord): RecordingSummary {
+  return {
+    id: r.id,
+    kind: r.kind,
+    sessionID: r.sessionID,
+    ...(r.sessionTitle !== undefined ? { sessionTitle: r.sessionTitle } : {}),
+    deviceID: r.deviceID,
+    ...(r.deviceName !== undefined ? { deviceName: r.deviceName } : {}),
+    state: r.state,
+    startedAt: r.startedAt,
+    ...(r.endedAt !== undefined ? { endedAt: r.endedAt } : {}),
+    ...(r.endReason !== undefined ? { endReason: r.endReason } : {}),
+    expiresAt: r.expiresAt,
+    bytes: r.bytes,
+    segments: r.segments,
+    events: r.events,
+    audio: r.audio,
+    redactions: r.redactions,
+  }
+}
+
+export class RecordingStore {
+  constructor(
+    readonly state: StateStore,
+    readonly blobs: BlobStore,
+    private readonly now: Clock,
+  ) {}
+
+  async get(userID: string, id: string): Promise<Versioned<RecordingRecord> | undefined> {
+    if (!isRecordingID(id)) return undefined
+    return this.state.get<RecordingRecord>(userID, RECORDINGS, id)
+  }
+
+  /** The record when it is the user's and not being deleted (every route's view). */
+  async visible(userID: string, id: string): Promise<RecordingRecord | undefined> {
+    const got = await this.get(userID, id)
+    return got && got.value.state !== "deleting" ? got.value : undefined
+  }
+
+  async list(userID: string): Promise<RecordingRecord[]> {
+    return (await this.state.list<RecordingRecord>(userID, RECORDINGS)).map((e) => e.value)
+  }
+
+  async create(userID: string, record: RecordingRecord): Promise<boolean> {
+    return (await this.state.put(userID, RECORDINGS, record.id, record, { ifVersion: 0 })).ok
+  }
+
+  /**
+   * Read-modify-write with CAS, retried on a lost race. `change` answers the next record, or undefined to leave it
+   * (the current one is answered). Missing → undefined.
+   */
+  async update(userID: string, id: string, change: (current: RecordingRecord) => RecordingRecord | undefined): Promise<{ record: RecordingRecord; changed: boolean } | undefined> {
+    for (let attempt = 0; attempt < 32; attempt++) {
+      const got = await this.get(userID, id)
+      if (!got) return undefined
+      const next = change(got.value)
+      if (!next) return { record: got.value, changed: false }
+      if ((await this.state.put(userID, RECORDINGS, id, next, { ifVersion: got.version })).ok) return { record: next, changed: true }
+    }
+    throw new Error("recording record kept changing")
+  }
+
+  async index<T = unknown>(userID: string, id: string): Promise<Entry<T>[]> {
+    return this.state.list<T>(userID, indexCollection(id))
+  }
+
+  async indexEntry<T = unknown>(userID: string, id: string, key: string): Promise<T | undefined> {
+    return (await this.state.get<T>(userID, indexCollection(id), key))?.value
+  }
+
+  /** Writes an index key once (ifVersion 0); false when it already exists. */
+  async putIndex(userID: string, id: string, key: string, value: unknown): Promise<boolean> {
+    return (await this.state.put(userID, indexCollection(id), key, value, { ifVersion: 0 })).ok
+  }
+
+  async putBlob(userID: string, body: BlobBody, mediaType: (typeof RECORDING_MEDIA_TYPES)[number], maxBytes: number, quotaBytes: number): Promise<BlobRef> {
+    return this.blobs.put(blobTenant(userID), body, mediaType, { maxBytes, quotaBytes, mediaTypes: RECORDING_MEDIA_TYPES })
+  }
+
+  async usage(userID: string): Promise<number> {
+    return (await this.blobs.usage(blobTenant(userID))).bytes
+  }
+
+  /** Every hash another recording of the user indexes (deletion keeps those). */
+  private async otherHashes(userID: string, except: ReadonlySet<string>): Promise<Set<string>> {
+    const hashes = new Set<string>()
+    for (const record of await this.list(userID)) {
+      if (except.has(record.id)) continue
+      for (const entry of await this.index<{ hash?: string }>(userID, record.id)) if (typeof entry.value.hash === "string") hashes.add(entry.value.hash)
+    }
+    return hashes
+  }
+
+  /** Step 1 helper: remembers the deletion (the sweep re-checks the index collection later). */
+  async tombstone(userID: string, id: string, at: number): Promise<void> {
+    await this.state.put(userID, TOMBSTONES, id, { at })
+  }
+
+  /**
+   * After a write into a recording (an index key `key` naming `hash`): when the recording is gone or being deleted,
+   * the write is undone (a deletion that ran meanwhile did not see it). Answers whether it was undone.
+   */
+  async undoIfDeleted(userID: string, id: string, key: string, hash: string): Promise<boolean> {
+    const got = await this.get(userID, id)
+    if (got && got.value.state !== "deleting") return false
+    const entry = await this.indexEntry<{ hash?: string }>(userID, id, key)
+    if (entry?.hash === hash) await this.state.delete(userID, indexCollection(id), key)
+    await this.dropIfUnindexed(userID, hash, this.now())
+    return true
+  }
+
+  /**
+   * The orphan pass of the sweep: tombstoned recordings whose record is gone get their index emptied again; rec~ blobs
+   * no recording indexes and untouched for ORPHAN_GRACE_MS are deleted. Answers how many items it removed.
+   */
+  async sweepOrphans(userID: string): Promise<number> {
+    const now = this.now()
+    let removed = 0
+    for (const tomb of await this.state.list<{ at?: number }>(userID, TOMBSTONES)) {
+      if (await this.get(userID, tomb.key)) continue // still deleting: finishDelete runs (or the sweep resumes it)
+      const entries = await this.index(userID, tomb.key)
+      for (const entry of entries) {
+        await this.state.delete(userID, indexCollection(tomb.key), entry.key)
+        removed++
+      }
+      if (!entries.length && now - (tomb.value.at ?? 0) >= TOMBSTONE_MS) await this.state.delete(userID, TOMBSTONES, tomb.key)
+    }
+    const indexed = await this.otherHashes(userID, new Set())
+    let cursor: string | undefined
+    const tenant = blobTenant(userID)
+    for (;;) {
+      const page = await this.blobs.list(tenant, { limit: 200, ...(cursor ? { cursor } : {}) })
+      for (const blob of page.items) {
+        if (indexed.has(blob.hash) || now - blob.touchedAt < ORPHAN_GRACE_MS) continue
+        if (await this.blobs.delete(tenant, blob.hash, { touchedBefore: now - ORPHAN_GRACE_MS + 1 })) removed++
+      }
+      if (!page.cursor) break
+      cursor = page.cursor
+    }
+    return removed
+  }
+
+  /** Steps 2–4 of a deletion (the record is already `deleting`): blobs, index, record. */
+  async finishDelete(userID: string, id: string): Promise<void> {
+    const got = await this.get(userID, id)
+    if (!got) return
+    const deletingAt = got.value.deletingAt ?? this.now()
+    const entries = await this.index<{ hash?: string }>(userID, id)
+    const keep = await this.otherHashes(userID, new Set([id]))
+    for (const hash of new Set(entries.map((e) => e.value.hash).filter((h): h is string => typeof h === "string"))) {
+      if (keep.has(hash)) continue
+      await this.blobs.delete(blobTenant(userID), hash, { touchedBefore: deletingAt + 1 })
+    }
+    for (const entry of entries) await this.state.delete(userID, indexCollection(id), entry.key)
+    await this.state.delete(userID, RECORDINGS, id)
+  }
+
+  /** Discards a blob nothing indexes (a lost first-write race). */
+  async dropIfUnindexed(userID: string, hash: string, at: number): Promise<void> {
+    if ((await this.otherHashes(userID, new Set())).has(hash)) return
+    await this.blobs.delete(blobTenant(userID), hash, { touchedBefore: at + 1 })
+  }
+}
+
+export interface StartFacts {
+  readonly id: string
+  readonly kind: RecordingSummary["kind"]
+  readonly sessionID: string
+  readonly sessionTitle?: string
+  readonly deviceID: string
+  readonly deviceName?: string
+  readonly clientID: string
+  readonly client: RecordingClient
+  readonly anchor: RecordingAnchor
+  readonly audio: boolean
+  readonly at: number
+}
+
+export function newRecord(facts: StartFacts, speech: SpeechFacts): RecordingRecord {
+  return {
+    id: facts.id,
+    kind: facts.kind,
+    sessionID: facts.sessionID,
+    ...(facts.sessionTitle ? { sessionTitle: facts.sessionTitle } : {}),
+    deviceID: facts.deviceID,
+    ...(facts.deviceName ? { deviceName: facts.deviceName } : {}),
+    state: "active",
+    startedAt: facts.at,
+    expiresAt: facts.at + RECORDING_LIMITS.retentionMs,
+    bytes: 0,
+    segments: 0,
+    events: 0,
+    audio: facts.audio,
+    redactions: 0,
+    clientID: facts.clientID,
+    client: facts.client,
+    anchor: facts.anchor,
+    consoleThrough: 0,
+    consoleGaps: 0,
+    hubPages: 0,
+    pages: 0,
+    eventBytes: 0,
+    lastEventAt: facts.at,
+    capNoted: [],
+    skipped: { cap: 0, failed: 0 },
+    ...speech,
+  }
+}
+
+/** The record ended (unchanged when it already is). */
+export function ended(record: RecordingRecord, reason: RecordingEndReason, at: number, graceUntil?: number): RecordingRecord | undefined {
+  if (record.state !== "active") return undefined
+  return { ...record, state: "ended", endedAt: at, endReason: reason, ...(graceUntil !== undefined ? { graceUntil } : {}) }
+}
+
+export type { RecordingAudioResult }