@glassly/engine 0.1.0-dev.0

package/src/services/MemoryStore.ts

@@ -0,0 +1,633 @@
+/**
+ * MemoryStore — the user's shared, phone-local memory timeline.
+ *
+ * One unified per-hour stream of what happened around the user — spoken
+ * transcript lines AND notes (manual, voice, auto) in one timeline — plus the
+ * hourly conversation summary that heads each session. Scoped to the Glassly
+ * USER (not to a miniapp): every miniapp that declares the MEMORY manifest
+ * permission reads and writes the same store through LocalMiniappRuntime's
+ * MEMORY_* handlers, and Settings > Memory manages it via engine.memory.
+ *
+ * A "session" is one clock hour that has entries, derived from entry
+ * timestamps at read time — nothing is stored per-session, so there is no
+ * session id to keep in sync.
+ *
+ * The store began life inside the Assist miniapp (its SessionStore); on first
+ * load it migrates Assist's per-app storage namespace into the shared
+ * user-scoped keys so existing history survives the move.
+ */
+
+import type {MemoryEntry, MemoryNoteSource, MemorySession, MemorySummary} from "@glassly/miniapp"
+
+import {searchMemoryEntries} from "../utils/memory/search"
+
+const KEY_ROOT = "memory_"
+const LOG_SUFFIX = "log"
+const SUMMARY_SUFFIX = "summaries"
+
+/** The pre-memory-layer Assist miniapp whose storage namespace we migrate. */
+const LEGACY_ASSIST_PACKAGE = "com.tetramo.assistant"
+const LEGACY_STORAGE_ROOT = "localstorage_"
+const LEGACY_LOG_KEY = "assistant:session-log"
+const LEGACY_SUMMARY_KEY = "assistant:hourly-summaries"
+// Assist's own pre-unification keys, migrated for users who never ran the
+// unified-schema Assist build.
+const LEGACY_TRANSCRIPT_KEY = "assistant:transcript-log"
+const LEGACY_NOTES_KEY = "assistant:notes"
+
+const HOUR_MS = 60 * 60 * 1000
+const DAY_MS = 24 * HOUR_MS
+
+/**
+ * How much timeline a tier can SEE. Retention gating is a read window, not a
+ * delete: pruning always keeps {@link EXTENDED_RETENTION}'s worth of data, and
+ * the active policy decides how far back reads reach. A lapsed subscriber's
+ * older timeline is frozen, not lost — upgrading again restores it instantly.
+ */
+export interface MemoryRetentionPolicy {
+  maxAgeMs: number
+  maxEntries: number
+  maxSummaries: number
+}
+
+/** Free-tier visibility: a 14-day rolling window. */
+export const STANDARD_RETENTION: MemoryRetentionPolicy = {
+  maxAgeMs: 14 * DAY_MS,
+  maxEntries: 4000,
+  maxSummaries: 24 * 14,
+}
+
+/**
+ * Plus/Pro visibility — and the store's PHYSICAL bounds for every tier. The
+ * entry cap also bounds the write cost — every persist re-serializes the
+ * whole timeline, so this cap is a perf ceiling as much as a product number.
+ */
+export const EXTENDED_RETENTION: MemoryRetentionPolicy = {
+  maxAgeMs: 180 * DAY_MS,
+  maxEntries: 24_000,
+  maxSummaries: 24 * 180,
+}
+const QUERY_LIMIT_CAP = 200
+const QUERY_LIMIT_DEFAULT = 60
+/**
+ * How long transcript appends coalesce before hitting disk. Each write
+ * re-serializes the entire timeline, so at conversational pace (a final
+ * utterance every few seconds) this turns O(n) work per line into O(n) per
+ * window. Short enough that an unexpected kill loses only the last few lines.
+ */
+const DEFAULT_WRITE_DEBOUNCE_MS = 3000
+
+export interface MemoryStoreBackend {
+  get(key: string): unknown | null
+  set(key: string, value: unknown): void
+  remove(key: string): void
+}
+
+export interface MemoryStoreHooks {
+  getUserId: () => Promise<string>
+  backend: MemoryStoreBackend
+  /**
+   * Debounce window for transcript-line writes, in ms. Appends coalesce into
+   * one serialization instead of re-stringifying the whole timeline per
+   * utterance. Set to 0 to persist synchronously (tests).
+   */
+  writeDebounceMs?: number
+  /**
+   * Visibility policy resolver, consulted at every read. A function (not a
+   * value) so the host can flip between STANDARD and EXTENDED as the user's
+   * subscription changes without rebuilding the store. Absent = standard.
+   * Never affects what is STORED — pruning is fixed at EXTENDED bounds.
+   */
+  getRetention?: () => MemoryRetentionPolicy
+}
+
+export interface MemoryStats {
+  entryCount: number
+  lineCount: number
+  noteCount: number
+  summaryCount: number
+  /** Epoch ms of the oldest entry, or null when empty. */
+  oldestAt: number | null
+}
+
+export function hourStartOf(ms: number): number {
+  return Math.floor(ms / HOUR_MS) * HOUR_MS
+}
+
+export function dayStartOf(ms: number): number {
+  const d = new Date(ms)
+  d.setHours(0, 0, 0, 0)
+  return d.getTime()
+}
+
+function makeId(): string {
+  return `e-${Date.now()}-${Math.random().toString(36).slice(2)}`
+}
+
+export class MemoryStore {
+  private entries: MemoryEntry[] = []
+  private summaries: MemorySummary[] = []
+  /** User the in-memory cache was loaded for; reload when identity changes. */
+  private loadedUserId: string | null = null
+  private loadPromise: Promise<void> | null = null
+  private readonly changeListeners = new Set<() => void>()
+  /** Pending debounced log write (transcript appends), if any. */
+  private logFlushTimer: ReturnType<typeof setTimeout> | null = null
+  private logDirty = false
+
+  constructor(private readonly hooks: MemoryStoreHooks) {}
+
+  /**
+   * Write any debounced changes out now. Call before the app backgrounds or
+   * terminates so a crash can't lose the coalesced tail of the timeline.
+   */
+  async flush(): Promise<void> {
+    if (this.logFlushTimer) {
+      clearTimeout(this.logFlushTimer)
+      this.logFlushTimer = null
+    }
+    if (this.logDirty) await this.persistLog()
+  }
+
+  /** Subscribe to mutations (adds, edits, deletes, clears). */
+  onChanged(listener: () => void): () => void {
+    this.changeListeners.add(listener)
+    return () => this.changeListeners.delete(listener)
+  }
+
+  // === Writes ===
+
+  async appendLine(input: {
+    text: string
+    speakerId: string | null
+    /** Resolved enrolled-speaker name (on-device speaker ID), when known. */
+    resolvedSpeakerName?: string | null
+    language: string | null
+    at: number
+  }): Promise<void> {
+    if (!input.text.trim()) return
+    await this.ensureLoaded()
+    this.entries.push({
+      id: makeId(),
+      kind: "line",
+      text: input.text.trim(),
+      at: input.at,
+      speakerId: input.speakerId,
+      ...(input.resolvedSpeakerName ? {resolvedSpeakerName: input.resolvedSpeakerName} : {}),
+      language: input.language,
+    })
+    this.prune()
+    // Transcript lines are the hot path (one per final utterance) and each
+    // persist re-serializes the whole timeline, so coalesce them. Everything
+    // else — notes, edits, deletes, summaries — still writes through
+    // immediately; those are user-visible and rare.
+    this.schedulePersistLog()
+    this.emitChanged()
+  }
+
+  /**
+   * Add a note. `at` targets the hour it belongs to — pass a timestamp inside
+   * a past hour to append to that session. Dedupes on normalized text within
+   * the same hour (auto-notes re-extract); resolves null on duplicate/empty.
+   */
+  async addNote(text: string, source: MemoryNoteSource, at: number = Date.now()): Promise<MemoryEntry | null> {
+    const body = text.trim()
+    if (!body) return null
+    await this.ensureLoaded()
+    const hour = hourStartOf(at)
+    const key = normalize(body)
+    if (this.entries.some((e) => e.kind === "note" && hourStartOf(e.at) === hour && normalize(e.text) === key)) {
+      return null
+    }
+    const entry: MemoryEntry = {id: makeId(), kind: "note", text: body, at, speakerId: null, language: null, source}
+    this.entries.push(entry)
+    this.entries.sort((a, b) => a.at - b.at)
+    this.prune()
+    await this.persistLog()
+    this.emitChanged()
+    return entry
+  }
+
+  /** Rewrite a note's text in place (Settings > Memory edit). */
+  async updateNote(id: string, text: string): Promise<boolean> {
+    const body = text.trim()
+    if (!body) return false
+    await this.ensureLoaded()
+    const entry = this.entries.find((e) => e.id === id && e.kind === "note")
+    if (!entry) return false
+    entry.text = body
+    await this.persistLog()
+    this.emitChanged()
+    return true
+  }
+
+  async removeEntry(id: string): Promise<boolean> {
+    await this.ensureLoaded()
+    const before = this.entries.length
+    this.entries = this.entries.filter((e) => e.id !== id)
+    if (this.entries.length === before) return false
+    await this.persistLog()
+    this.emitChanged()
+    return true
+  }
+
+  /** Delete every entry (and summary) in an hour, or a whole day of hours. */
+  async removeScope(scope: "session" | "day", at: number): Promise<void> {
+    await this.ensureLoaded()
+    const inScope =
+      scope === "day"
+        ? (ms: number) => dayStartOf(ms) === dayStartOf(at)
+        : (ms: number) => hourStartOf(ms) === hourStartOf(at)
+    this.entries = this.entries.filter((e) => !inScope(e.at))
+    this.summaries = this.summaries.filter((s) => !inScope(s.hourStart))
+    await this.persistLog()
+    await this.persistSummaries()
+    this.emitChanged()
+  }
+
+  /** Drop the entire timeline: every entry and every summary. */
+  async clear(): Promise<void> {
+    await this.ensureLoaded()
+    this.entries = []
+    this.summaries = []
+    await this.persistLog()
+    await this.persistSummaries()
+    this.emitChanged()
+  }
+
+  async addSummary(summary: MemorySummary): Promise<void> {
+    await this.ensureLoaded()
+    const {maxSummaries} = EXTENDED_RETENTION
+    this.summaries = this.summaries.filter((s) => s.hourStart !== summary.hourStart)
+    this.summaries.push(summary)
+    if (this.summaries.length > maxSummaries) {
+      this.summaries = this.summaries.sort((a, b) => a.hourStart - b.hourStart).slice(-maxSummaries)
+    }
+    await this.persistSummaries()
+    this.emitChanged()
+  }
+
+  // === Reads ===
+  //
+  // Every read goes through the VISIBLE view: entries inside the active
+  // tier's window. Older data may still be stored (see prune) — it is frozen,
+  // not deleted, so an upgrade widens these views instantly.
+
+  /** Entries in [sinceMs, untilMs), newest last. */
+  async window(sinceMs: number, untilMs: number = Date.now()): Promise<MemoryEntry[]> {
+    await this.ensureLoaded()
+    return this.visibleEntries().filter((e) => e.at >= sinceMs && e.at < untilMs)
+  }
+
+  /** All note entries, newest first (Settings > Memory list). */
+  async notes(): Promise<MemoryEntry[]> {
+    await this.ensureLoaded()
+    return this.visibleEntries()
+      .filter((e) => e.kind === "note")
+      .sort((a, b) => b.at - a.at)
+  }
+
+  async stats(): Promise<MemoryStats> {
+    await this.ensureLoaded()
+    const visible = this.visibleEntries()
+    const noteCount = visible.filter((e) => e.kind === "note").length
+    return {
+      entryCount: visible.length,
+      lineCount: visible.length - noteCount,
+      noteCount,
+      summaryCount: this.visibleSummaries().filter((s) => s.text.trim()).length,
+      oldestAt: visible.length > 0 ? visible[0].at : null,
+    }
+  }
+
+  /** All sessions (hours with entries), newest hour first. */
+  async sessionList(): Promise<MemorySession[]> {
+    await this.ensureLoaded()
+    const byHour = new Map<number, MemoryEntry[]>()
+    for (const e of this.visibleEntries()) {
+      const h = hourStartOf(e.at)
+      const list = byHour.get(h) ?? []
+      list.push(e)
+      byHour.set(h, list)
+    }
+    const summaryByHour = new Map(this.visibleSummaries().map((s) => [s.hourStart, s.text]))
+    return [...byHour.entries()]
+      .map(([hourStart, entries]) => {
+        entries.sort((a, b) => a.at - b.at)
+        return {
+          hourStart,
+          entries,
+          summary: (summaryByHour.get(hourStart) ?? "").trim() || null,
+          lineCount: entries.filter((e) => e.kind === "line").length,
+          noteCount: entries.filter((e) => e.kind === "note").length,
+        }
+      })
+      .sort((a, b) => b.hourStart - a.hourStart)
+  }
+
+  /**
+   * Query the FULL store by absolute-time window and keyword — the executor
+   * behind LLM history-search tools. Newest last, so the limit keeps the most
+   * recent matches. `contains` is an exact substring; `terms` is fuzzy any-of
+   * matching (mistranscribed-name tolerant) — see utils/memory/search.ts.
+   */
+  async query(q: {
+    sinceMs?: number
+    untilMs?: number
+    contains?: string
+    terms?: string[]
+    limit?: number
+  }): Promise<MemoryEntry[]> {
+    return (await this.search(q)).entries
+  }
+
+  /**
+   * query() plus `windowCount` — how many entries the TIME window held before
+   * keyword filtering, so an LLM caller can distinguish "keyword matched
+   * nothing" from "history doesn't reach that far back" without a retry.
+   */
+  async search(q: {
+    sinceMs?: number
+    untilMs?: number
+    contains?: string
+    terms?: string[]
+    limit?: number
+  }): Promise<{entries: MemoryEntry[]; windowCount: number}> {
+    await this.ensureLoaded()
+    const limit = q.limit && q.limit > 0 ? Math.min(q.limit, QUERY_LIMIT_CAP) : QUERY_LIMIT_DEFAULT
+    return searchMemoryEntries(this.visibleEntries(), {
+      sinceMs: q.sinceMs,
+      untilMs: q.untilMs,
+      contains: q.contains,
+      terms: q.terms,
+      limit,
+    })
+  }
+
+  async summaryList(): Promise<MemorySummary[]> {
+    await this.ensureLoaded()
+    return this.visibleSummaries().sort((a, b) => b.hourStart - a.hourStart)
+  }
+
+  /** Most recent COMPLETED hour with lines but no summary, or null. */
+  async pendingSummaryHour(nowMs: number = Date.now()): Promise<number | null> {
+    await this.ensureLoaded()
+    const currentHour = hourStartOf(nowMs)
+    const summarized = new Set(this.summaries.map((s) => s.hourStart))
+    const hours = new Set<number>()
+    for (const e of this.visibleEntries()) {
+      if (e.kind !== "line") continue
+      const h = hourStartOf(e.at)
+      if (h < currentHour && !summarized.has(h)) hours.add(h)
+    }
+    if (hours.size === 0) return null
+    return Math.max(...hours)
+  }
+
+  /** Plain-text export of a scope, for the OS share sheet. */
+  async exportText(scope: "session" | "day" | "all", at?: number): Promise<string> {
+    const sessions = (await this.sessionList()).filter((s) => {
+      if (scope === "all") return true
+      if (at == null) return false
+      if (scope === "day") return dayStartOf(s.hourStart) === dayStartOf(at)
+      return s.hourStart === hourStartOf(at)
+    })
+    if (sessions.length === 0) return "No session history to export."
+
+    const dayFmt = (ms: number) =>
+      new Date(ms).toLocaleDateString(undefined, {weekday: "long", year: "numeric", month: "long", day: "numeric"})
+    const hourFmt = (ms: number) => new Date(ms).toLocaleTimeString(undefined, {hour: "numeric"})
+    const timeFmt = (ms: number) => new Date(ms).toLocaleTimeString(undefined, {hour: "numeric", minute: "2-digit"})
+
+    const parts: string[] = []
+    let lastDay: number | null = null
+    for (const s of [...sessions].sort((a, b) => a.hourStart - b.hourStart)) {
+      const day = dayStartOf(s.hourStart)
+      if (day !== lastDay) {
+        parts.push(`\n=== ${dayFmt(day)} ===`)
+        lastDay = day
+      }
+      parts.push(`\n[${hourFmt(s.hourStart)}–${hourFmt(s.hourStart + HOUR_MS)}]`)
+      if (s.summary) parts.push(`Summary: ${s.summary}`)
+      for (const e of s.entries) {
+        const who = e.kind === "note" ? "NOTE" : (e.speakerId ?? "—")
+        parts.push(`  ${timeFmt(e.at)}  ${who}: ${e.text}`)
+      }
+    }
+    return `Memory session history\n${parts.join("\n").trim()}\n`
+  }
+
+  // === Load / persist ===
+
+  private async ensureLoaded(): Promise<void> {
+    const userId = (await this.hooks.getUserId()).trim()
+    if (!userId) throw new Error("Glassly user identity is unavailable")
+    if (this.loadedUserId === userId) return
+    if (!this.loadPromise) {
+      this.loadPromise = this.loadFor(userId).finally(() => {
+        this.loadPromise = null
+      })
+    }
+    await this.loadPromise
+  }
+
+  private async loadFor(userId: string): Promise<void> {
+    // Don't let an identity switch discard lines still sitting in the debounce
+    // window — they belong to the OUTGOING user, whose key is still loaded.
+    await this.flush()
+    this.entries = []
+    this.summaries = []
+    const rawLog = this.hooks.backend.get(this.key(userId, LOG_SUFFIX))
+    if (rawLog != null) {
+      this.entries = parseArray(rawLog).filter(isEntry)
+    } else {
+      this.migrateFromAssist(userId)
+    }
+    const rawSummaries = this.hooks.backend.get(this.key(userId, SUMMARY_SUFFIX))
+    if (rawSummaries != null) {
+      this.summaries = parseArray(rawSummaries).filter(isSummary)
+    }
+    this.loadedUserId = userId
+    this.prune()
+  }
+
+  /**
+   * One-time migration: fold the Assist miniapp's per-app store (the previous
+   * home of this timeline) into the shared user-scoped keys. Assist's old keys
+   * are left in place; its new build reads through the memory bridge instead.
+   */
+  private migrateFromAssist(userId: string): void {
+    const legacyPrefix = `${LEGACY_STORAGE_ROOT}${userId}_${LEGACY_ASSIST_PACKAGE}_`
+    try {
+      const migrated: MemoryEntry[] = []
+      const rawLog = this.hooks.backend.get(legacyPrefix + LEGACY_LOG_KEY)
+      if (rawLog != null) {
+        migrated.push(...parseArray(rawLog).filter(isEntry))
+      } else {
+        // Pre-unification Assist: separate transcript log + notes stores.
+        for (const v of parseArray(this.hooks.backend.get(legacyPrefix + LEGACY_TRANSCRIPT_KEY))) {
+          const e = v as Record<string, unknown>
+          if (typeof e.text === "string" && typeof e.at === "number") {
+            migrated.push({
+              id: makeId(),
+              kind: "line",
+              text: e.text,
+              at: e.at,
+              speakerId: typeof e.speakerId === "string" ? e.speakerId : null,
+              language: typeof e.language === "string" ? e.language : null,
+            })
+          }
+        }
+        for (const v of parseArray(this.hooks.backend.get(legacyPrefix + LEGACY_NOTES_KEY))) {
+          const n = v as Record<string, unknown>
+          if (typeof n.text === "string" && typeof n.createdAt === "number") {
+            migrated.push({
+              id: makeId(),
+              kind: "note",
+              text: n.text,
+              at: n.createdAt,
+              speakerId: null,
+              language: null,
+              source: n.source === "voice" || n.source === "auto" ? n.source : "ui",
+            })
+          }
+        }
+      }
+      migrated.sort((a, b) => a.at - b.at)
+      this.entries = migrated
+      if (migrated.length > 0) this.hooks.backend.set(this.key(userId, LOG_SUFFIX), JSON.stringify(migrated))
+
+      const rawSummaries = this.hooks.backend.get(legacyPrefix + LEGACY_SUMMARY_KEY)
+      if (rawSummaries != null) {
+        const summaries = parseArray(rawSummaries).filter(isSummary)
+        this.summaries = summaries
+        if (summaries.length > 0) this.hooks.backend.set(this.key(userId, SUMMARY_SUFFIX), JSON.stringify(summaries))
+      }
+      if (this.entries.length > 0 || this.summaries.length > 0) {
+        console.log(
+          `MemoryStore: migrated ${this.entries.length} entries + ${this.summaries.length} summaries from Assist`,
+        )
+      }
+    } catch (err) {
+      console.warn("MemoryStore: Assist migration failed:", err instanceof Error ? err.message : err)
+    }
+  }
+
+  private retention(): MemoryRetentionPolicy {
+    return this.hooks.getRetention?.() ?? STANDARD_RETENTION
+  }
+
+  /** Entries inside the active tier's visibility window, oldest first. */
+  private visibleEntries(): MemoryEntry[] {
+    const cutoff = Date.now() - this.retention().maxAgeMs
+    return this.entries.filter((e) => e.at >= cutoff)
+  }
+
+  private visibleSummaries(): MemorySummary[] {
+    const cutoff = Date.now() - this.retention().maxAgeMs
+    return this.summaries.filter((s) => s.hourStart >= cutoff)
+  }
+
+  /**
+   * Physical bounds, ALWAYS the extended policy regardless of tier. A free or
+   * lapsed user's older timeline stays on disk (reads just can't see past
+   * their window) so upgrading — or re-upgrading — restores it rather than
+   * finding it deleted. Deleting remains the user's call: clear()/removeScope
+   * operate on the physical store.
+   */
+  private prune(): void {
+    const {maxAgeMs, maxEntries} = EXTENDED_RETENTION
+    const cutoff = Date.now() - maxAgeMs
+    this.entries = this.entries.filter((e) => e.at >= cutoff)
+    if (this.entries.length > maxEntries) this.entries = this.entries.slice(-maxEntries)
+  }
+
+  private key(userId: string, suffix: string): string {
+    return `${KEY_ROOT}${userId}_${suffix}`
+  }
+
+  /**
+   * Mark the log dirty and arm the debounce timer. Repeated appends inside the
+   * window collapse into a single serialization; the first append after a
+   * flush starts a fresh window (trailing-edge, so a steady stream of speech
+   * still lands on disk every `writeDebounceMs`).
+   */
+  private schedulePersistLog(): void {
+    const delay = this.hooks.writeDebounceMs ?? DEFAULT_WRITE_DEBOUNCE_MS
+    if (delay <= 0) {
+      void this.persistLog()
+      return
+    }
+    this.logDirty = true
+    if (this.logFlushTimer) return
+    this.logFlushTimer = setTimeout(() => {
+      this.logFlushTimer = null
+      void this.persistLog().catch((err) =>
+        console.warn("MemoryStore: debounced log write failed:", err instanceof Error ? err.message : err),
+      )
+    }, delay)
+  }
+
+  private async persistLog(): Promise<void> {
+    // Any write of the full array satisfies whatever the debounce was holding.
+    this.logDirty = false
+    if (this.logFlushTimer) {
+      clearTimeout(this.logFlushTimer)
+      this.logFlushTimer = null
+    }
+    if (this.loadedUserId == null) return
+    this.hooks.backend.set(this.key(this.loadedUserId, LOG_SUFFIX), JSON.stringify(this.entries))
+  }
+
+  private async persistSummaries(): Promise<void> {
+    if (this.loadedUserId == null) return
+    this.hooks.backend.set(this.key(this.loadedUserId, SUMMARY_SUFFIX), JSON.stringify(this.summaries))
+  }
+
+  private emitChanged(): void {
+    for (const listener of this.changeListeners) {
+      try {
+        listener()
+      } catch (err) {
+        console.warn("MemoryStore: onChanged listener threw:", err instanceof Error ? err.message : err)
+      }
+    }
+  }
+}
+
+/** Stored values may be a JSON string (SimpleStorage writes) or a raw array. */
+function parseArray(raw: unknown): unknown[] {
+  try {
+    if (typeof raw === "string") {
+      const parsed = JSON.parse(raw) as unknown
+      return Array.isArray(parsed) ? parsed : []
+    }
+    return Array.isArray(raw) ? raw : []
+  } catch {
+    return []
+  }
+}
+
+function normalize(text: string): string {
+  return text
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, " ")
+    .trim()
+}
+
+function isEntry(v: unknown): v is MemoryEntry {
+  if (!v || typeof v !== "object") return false
+  const e = v as Record<string, unknown>
+  return (
+    typeof e.id === "string" &&
+    (e.kind === "line" || e.kind === "note") &&
+    typeof e.text === "string" &&
+    typeof e.at === "number"
+  )
+}
+
+function isSummary(v: unknown): v is MemorySummary {
+  if (!v || typeof v !== "object") return false
+  const s = v as Record<string, unknown>
+  return typeof s.hourStart === "number" && typeof s.text === "string" && typeof s.createdAt === "number"
+}