@openmarket/rooms-client 0.1.0

package/src/agent/topic-inbox.ts

@@ -0,0 +1,297 @@
+/**
+ * The open-core topic model: one room's registry rows plus the viewer's
+ * per-bucket state (cursor, attention, unread), with the unread math,
+ * muted exclusions, merge roll-up, and the deterministic catch-up order
+ * that every surface (GUI store, TUI, inbox, keyboard nav) consumes
+ * instead of reimplementing semantics.
+ *
+ * A BUCKET is a topicId, or the reserved '' key (UNTOPICKED_BUCKET) for
+ * the room's untopicked linear messages, matching the durable store's
+ * reserved empty-string cursor row. Per the phase 2 contract the buckets
+ * are independent: reading the linear lane never marks a topic seen, and
+ * vice versa.
+ *
+ * This model is a pure state machine: no timers, no sockets, no writes.
+ * Cursor ACKs happen exclusively through the view batcher; the model only
+ * mirrors positions it is told about.
+ */
+
+import type {
+  RoomTopic,
+  RoomTopicAttention,
+  RoomTopicBucketState,
+  RoomTopicsResultPayload,
+} from "../shared/rooms-protocol.js";
+
+/** The reserved bucket key for untopicked (linear) messages. */
+export const UNTOPICKED_BUCKET = "";
+
+export interface TopicInboxItem {
+  /** Bucket key: a topicId, or UNTOPICKED_BUCKET for the linear lane. */
+  key: string;
+  /** The registry row; undefined for the untopicked bucket. */
+  topic: RoomTopic | undefined;
+  state: RoomTopicBucketState;
+  /** Unread rolled up from merged-away alias buckets (survivors only). */
+  aliasUnread: number;
+}
+
+export interface TopicInboxEntry {
+  seq: number;
+  userId: string;
+  topicId?: string | undefined;
+}
+
+function emptyBucket(): RoomTopicBucketState {
+  return { lastSeq: 0, unreadCount: 0, cursor: 0, attention: "default" };
+}
+
+export class RoomTopicInbox {
+  readonly room: string;
+  /** True once a withState hydration has landed; counts are trustworthy. */
+  hydrated = false;
+  headSeq = 0;
+  private readonly topics = new Map<string, RoomTopic>();
+  private readonly buckets = new Map<string, RoomTopicBucketState>();
+
+  constructor(room: string) {
+    this.room = room;
+  }
+
+  /** Replace registry rows and per-bucket state from a withState TOPICS
+   *  reply. Idempotent; later live frames layer on top.
+   *
+   *  Positions only move FORWARD: the server read can lag local truth by
+   *  the ack debounce plus the relay's cursor write buffer, so a rehydrate
+   *  (TOPIC_UPDATED / ENTRY_UPDATED are hot triggers) must never resurrect
+   *  a just-cleared badge. Cursors and lastSeq merge as max(local, server);
+   *  a bucket whose merged cursor reaches its lastSeq is read, whatever
+   *  count the stale server row carried. */
+  hydrate(payload: Pick<RoomTopicsResultPayload, "topics" | "state" | "headSeq">): void {
+    this.topics.clear();
+    for (const topic of payload.topics) this.topics.set(topic.topicId, topic);
+    const previous = new Map(this.buckets);
+    this.buckets.clear();
+    for (const [key, state] of Object.entries(payload.state ?? {})) {
+      const local = previous.get(key);
+      const cursor = Math.max(state.cursor, local?.cursor ?? 0);
+      const lastSeq = Math.max(state.lastSeq, local?.lastSeq ?? 0);
+      this.buckets.set(key, {
+        ...state,
+        cursor,
+        lastSeq,
+        unreadCount: cursor >= lastSeq ? 0 : state.unreadCount,
+      });
+    }
+    if (!this.buckets.has(UNTOPICKED_BUCKET)) {
+      this.buckets.set(UNTOPICKED_BUCKET, emptyBucket());
+    }
+    this.headSeq = Math.max(this.headSeq, payload.headSeq ?? 0);
+    this.hydrated = true;
+  }
+
+  topicFor(topicId: string): RoomTopic | undefined {
+    return this.topics.get(topicId);
+  }
+
+  /** Follow a merged husk to its survivor (chains are flattened server-side
+   *  to one hop). A live id, unknown id, or the untopicked key returns
+   *  itself. */
+  survivorOf(key: string): string {
+    if (key === UNTOPICKED_BUCKET) return key;
+    const merged = this.topics.get(key)?.mergedInto;
+    return merged || key;
+  }
+
+  /** Merged-away buckets whose survivor is the given topic. */
+  aliasesOf(topicId: string): string[] {
+    const aliases: string[] = [];
+    for (const topic of this.topics.values()) {
+      if (topic.mergedInto === topicId) aliases.push(topic.topicId);
+    }
+    return aliases;
+  }
+
+  /** Registry rows in listed (creation) order, husks excluded. */
+  openTopics(options?: { includeResolved?: boolean }): RoomTopic[] {
+    const rows: RoomTopic[] = [];
+    for (const topic of this.topics.values()) {
+      if (topic.mergedInto) continue;
+      if (!options?.includeResolved && topic.resolved) continue;
+      rows.push(topic);
+    }
+    return rows;
+  }
+
+  bucketFor(key: string): RoomTopicBucketState {
+    return this.buckets.get(key) ?? emptyBucket();
+  }
+
+  /** Every bucket still carrying unread, muted and merged husks included:
+   *  the explicit mark-channel-read verb clears ALL of them (a muted or
+   *  merged bucket left unacked would resurrect on unmute/reopen). */
+  unreadBuckets(): Array<{ key: string; lastSeq: number }> {
+    const rows: Array<{ key: string; lastSeq: number }> = [];
+    for (const [key, bucket] of this.buckets) {
+      if (bucket.unreadCount > 0 && bucket.lastSeq > bucket.cursor) {
+        rows.push({ key, lastSeq: bucket.lastSeq });
+      }
+    }
+    return rows;
+  }
+
+  attentionFor(topicId: string): RoomTopicAttention {
+    return this.bucketFor(topicId).attention;
+  }
+
+  /** A registry mutation arrived (TOPIC_UPDATED, or a verb result echo). */
+  applyTopicUpdated(topic: RoomTopic): void {
+    this.topics.set(topic.topicId, topic);
+    if (!this.buckets.has(topic.topicId)) {
+      this.buckets.set(topic.topicId, emptyBucket());
+    }
+  }
+
+  /**
+   * A live entry arrived. viewedKey is the bucket the viewer is CURRENTLY
+   * looking at (or null): entries landing in the viewed bucket advance the
+   * local cursor instead of counting unread (the durable ACK rides the
+   * view batcher separately). Own posts never count unread, and an own
+   * post into a topic mirrors the server's auto-follow (mute survives).
+   */
+  applyEntry(
+    entry: TopicInboxEntry,
+    context: { selfUserId: string; viewedKey?: string | null },
+  ): void {
+    if (!Number.isFinite(entry.seq) || entry.seq <= 0) return;
+    const key = entry.topicId || UNTOPICKED_BUCKET;
+    let bucket = this.buckets.get(key);
+    if (!bucket) {
+      bucket = emptyBucket();
+      this.buckets.set(key, bucket);
+    }
+    bucket.lastSeq = Math.max(bucket.lastSeq, entry.seq);
+    this.headSeq = Math.max(this.headSeq, entry.seq);
+
+    const own = entry.userId === context.selfUserId;
+    if (own) {
+      if (key !== UNTOPICKED_BUCKET && bucket.attention !== "mute") {
+        bucket.attention = "follow";
+      }
+      return;
+    }
+    if (context.viewedKey === key) {
+      bucket.cursor = Math.max(bucket.cursor, entry.seq);
+      return;
+    }
+    bucket.unreadCount += 1;
+  }
+
+  /** Mirror an attention change (a TOPIC_SET_ATTENTION result, optimistic
+   *  or confirmed). */
+  applyAttention(topicId: string, attention: RoomTopicAttention): void {
+    let bucket = this.buckets.get(topicId);
+    if (!bucket) {
+      bucket = emptyBucket();
+      this.buckets.set(topicId, bucket);
+    }
+    bucket.attention = attention;
+  }
+
+  /**
+   * The viewer saw a bucket up to seq (the view batcher owns the durable
+   * ACK; this mirrors it locally). Catching up to the bucket head clears
+   * its count; a partial view keeps the residual count as an upper bound
+   * until the next hydration trues it up.
+   */
+  noteViewed(key: string, seq: number): void {
+    if (!Number.isFinite(seq) || seq <= 0) return;
+    let bucket = this.buckets.get(key);
+    if (!bucket) {
+      bucket = emptyBucket();
+      this.buckets.set(key, bucket);
+    }
+    bucket.cursor = Math.max(bucket.cursor, seq);
+    if (bucket.cursor >= bucket.lastSeq) bucket.unreadCount = 0;
+  }
+
+  /**
+   * The channel-level unread badge for a topic-aware room: every non-muted
+   * bucket's count, untopicked and resolved included (new activity in a
+   * resolved topic still deserves attention), husks counted once (their
+   * unread also rolls into the survivor's inbox item for display).
+   */
+  channelUnread(): number {
+    let total = 0;
+    for (const bucket of this.buckets.values()) {
+      if (bucket.attention === "mute") continue;
+      total += bucket.unreadCount;
+    }
+    return total;
+  }
+
+  /**
+   * The inbox, in THE deterministic catch-up order every surface shares:
+   * the untopicked lane first (the channel's main stream), then followed
+   * topics, then the rest; within each group oldest activity first
+   * (ascending lastSeq, topicId tie-break). Muted buckets never appear;
+   * merged husks roll their unread into the survivor's aliasUnread; a
+   * resolved topic appears only while it carries unread.
+   */
+  inboxItems(): TopicInboxItem[] {
+    const items: TopicInboxItem[] = [];
+    const untopicked = this.bucketFor(UNTOPICKED_BUCKET);
+    if (untopicked.unreadCount > 0 && untopicked.attention !== "mute") {
+      items.push({
+        key: UNTOPICKED_BUCKET,
+        topic: undefined,
+        state: { ...untopicked },
+        aliasUnread: 0,
+      });
+    }
+
+    const grouped: TopicInboxItem[] = [];
+    for (const topic of this.topics.values()) {
+      if (topic.mergedInto) continue;
+      const state = this.bucketFor(topic.topicId);
+      if (state.attention === "mute") continue;
+      let aliasUnread = 0;
+      for (const alias of this.aliasesOf(topic.topicId)) {
+        const aliasState = this.bucketFor(alias);
+        if (aliasState.attention === "mute") continue;
+        aliasUnread += aliasState.unreadCount;
+      }
+      if (state.unreadCount + aliasUnread === 0) continue;
+      grouped.push({ key: topic.topicId, topic, state: { ...state }, aliasUnread });
+    }
+    grouped.sort((a, b) => {
+      const aFollow = a.state.attention === "follow" ? 0 : 1;
+      const bFollow = b.state.attention === "follow" ? 0 : 1;
+      if (aFollow !== bFollow) return aFollow - bFollow;
+      if (a.state.lastSeq !== b.state.lastSeq) {
+        return a.state.lastSeq - b.state.lastSeq;
+      }
+      return a.key < b.key ? -1 : a.key > b.key ? 1 : 0;
+    });
+    items.push(...grouped);
+    return items;
+  }
+
+  /**
+   * The next bucket a catch-up walk should visit: the first inbox item
+   * after the given key (wrapping), or null when nothing is unread. The
+   * walk order is inboxItems(); keyboard nav and the catch-up flow step
+   * through the same list a user sees.
+   */
+  nextUnread(afterKey?: string | null): string | null {
+    const items = this.inboxItems();
+    if (items.length === 0) return null;
+    if (afterKey === undefined || afterKey === null) {
+      return items[0]?.key ?? null;
+    }
+    const index = items.findIndex((item) => item.key === afterKey);
+    if (index < 0) return items[0]?.key ?? null;
+    const next = items[(index + 1) % items.length];
+    return next && next.key !== afterKey ? next.key : null;
+  }
+}

package/src/agent/topic-view-batcher.ts

@@ -0,0 +1,134 @@
+/**
+ * View-time cursor batching: the ONLY path from "a surface is showing
+ * messages" to a cursor ACK. Surfaces report views (beginView, noteSeq,
+ * endView); this batcher applies the locked phase 2 contract on top:
+ *
+ * - Dwell gating: a view must survive dwellMs before anything is acked, so
+ *   a keyboard flash-through (next-unread skimming past a topic) never
+ *   marks it read. "Marks read only after actual view time."
+ * - Batching: once dwelled, the highest seen seq forwards into the
+ *   downstream ACK debouncer (one ACK frame per bucket per debounce
+ *   window at most, relay-side write buffering below that). Per-message
+ *   cursor writes are impossible by construction: the UI layer has no
+ *   other ack path.
+ *
+ * A bucket key of '' (UNTOPICKED_BUCKET) acks the room-wide cursor; any
+ * other key acks that topic's cursor.
+ */
+
+export interface TopicViewBatcherOptions {
+  /** Forward a dwelled view position; wire this to RoomAckDebouncer.schedule. */
+  scheduleAck: (room: string, seq: number, topicId?: string) => void;
+  /** Continuous view time required before the first ack (default 600ms). */
+  dwellMs?: number | undefined;
+  /** Injectable timers for tests. */
+  setTimeoutFn?: ((fn: () => void, ms: number) => unknown) | undefined;
+  clearTimeoutFn?: ((handle: unknown) => void) | undefined;
+}
+
+interface ViewSession {
+  room: string;
+  key: string;
+  maxSeq: number;
+  dwelled: boolean;
+  timer: unknown;
+}
+
+function viewKey(room: string, key: string): string {
+  return `${encodeURIComponent(room)}:${encodeURIComponent(key)}`;
+}
+
+export class TopicViewBatcher {
+  private readonly scheduleAck: TopicViewBatcherOptions["scheduleAck"];
+  private readonly dwellMs: number;
+  private readonly setTimeoutFn: (fn: () => void, ms: number) => unknown;
+  private readonly clearTimeoutFn: (handle: unknown) => void;
+  private readonly sessions = new Map<string, ViewSession>();
+
+  constructor(options: TopicViewBatcherOptions) {
+    this.scheduleAck = options.scheduleAck;
+    this.dwellMs = options.dwellMs ?? 600;
+    this.setTimeoutFn =
+      options.setTimeoutFn ??
+      ((fn, ms) => {
+        const timer = setTimeout(fn, ms);
+        (timer as { unref?: () => void }).unref?.();
+        return timer;
+      });
+    this.clearTimeoutFn = options.clearTimeoutFn ?? ((handle) => clearTimeout(handle as never));
+  }
+
+  /** A surface started showing a bucket. Idempotent per (room, key). */
+  beginView(room: string, key: string): void {
+    const id = viewKey(room, key);
+    if (this.sessions.has(id)) return;
+    const session: ViewSession = { room, key, maxSeq: 0, dwelled: false, timer: undefined };
+    session.timer = this.setTimeoutFn(() => {
+      session.dwelled = true;
+      session.timer = undefined;
+      this.forward(session);
+    }, this.dwellMs);
+    this.sessions.set(id, session);
+  }
+
+  /** The highest seq currently visible in a bucket the surface is showing.
+   *  Before dwell it accumulates; after dwell it forwards (debounced
+   *  downstream). Calls for a bucket not being viewed are ignored: only
+   *  actual view time acks. */
+  noteSeq(room: string, key: string, seq: number): void {
+    if (!Number.isFinite(seq) || seq <= 0) return;
+    const session = this.sessions.get(viewKey(room, key));
+    if (!session) return;
+    if (seq <= session.maxSeq) return;
+    session.maxSeq = seq;
+    if (session.dwelled) this.forward(session);
+  }
+
+  /** The surface stopped showing the bucket. An un-dwelled view (a
+   *  flash-through) is discarded without acking. */
+  endView(room: string, key: string): void {
+    const id = viewKey(room, key);
+    const session = this.sessions.get(id);
+    if (!session) return;
+    if (session.timer !== undefined) {
+      this.clearTimeoutFn(session.timer);
+      session.timer = undefined;
+    }
+    this.sessions.delete(id);
+  }
+
+  /** True while the bucket is being viewed (dwelled or not). */
+  isViewing(room: string, key: string): boolean {
+    return this.sessions.has(viewKey(room, key));
+  }
+
+  /** The bucket key currently viewed in a room, or null. */
+  viewedKey(room: string): string | null {
+    for (const session of this.sessions.values()) {
+      if (session.room === room) return session.key;
+    }
+    return null;
+  }
+
+  /** Force every dwelled view forward (window hide, disconnect boundary).
+   *  Un-dwelled views stay pending: flushing must not turn a flash-through
+   *  into a read. */
+  flush(): void {
+    for (const session of this.sessions.values()) {
+      if (session.dwelled) this.forward(session);
+    }
+  }
+
+  close(): void {
+    for (const session of this.sessions.values()) {
+      if (session.timer !== undefined) this.clearTimeoutFn(session.timer);
+    }
+    this.flush();
+    this.sessions.clear();
+  }
+
+  private forward(session: ViewSession): void {
+    if (session.maxSeq <= 0) return;
+    this.scheduleAck(session.room, session.maxSeq, session.key === "" ? undefined : session.key);
+  }
+}