@anthusai/papyrus 5.56.0 → 5.57.0

package/components/conversation-context.tsx

@@ -0,0 +1,52 @@
+"use client";
+
+import { createContext, useContext, type ReactNode } from "react";
+import type { ConversationAnchor, ConversationMessage } from "../lib/conversation";
+
+/**
+ * Where conversations are read and written. The newsroom provides the network one; a demo or a test provides the in-memory one. A
+ * component that finds no store shows no conversation at all.
+ */
+export type ConversationStore = {
+  /** Who the optimistic Message says wrote it, until the saved one replaces it. */
+  authorLabel: string;
+  load: (anchor: ConversationAnchor) => Promise<ConversationMessage[]>;
+  append: (input: { anchor: ConversationAnchor; body: string; parentMessageId: string | null }) => Promise<ConversationMessage>;
+  /** Message counts by Reference lineage, for the feed cards. */
+  counts: () => Promise<Map<string, number>>;
+};
+
+const ConversationStoreContext = createContext<ConversationStore | null>(null);
+
+export function ConversationStoreProvider({ store, children }: { store: ConversationStore; children: ReactNode }) {
+  return <ConversationStoreContext.Provider value={store}>{children}</ConversationStoreContext.Provider>;
+}
+
+export function useConversationStore(): ConversationStore | null {
+  return useContext(ConversationStoreContext);
+}
+
+/** A store that keeps everything in memory: the demo newsroom, and the tests. */
+export function createMemoryConversationStore(authorLabel: string, seed: Record<string, ConversationMessage[]> = {}): ConversationStore {
+  const byAnchor = new Map<string, ConversationMessage[]>(Object.entries(seed));
+  const keyOf = (anchor: ConversationAnchor) => `${anchor.kind}#${anchor.lineageId ?? ""}`;
+  return {
+    authorLabel,
+    load: async (anchor) => [...(byAnchor.get(keyOf(anchor)) ?? [])],
+    append: async ({ anchor, body, parentMessageId }) => {
+      const list = byAnchor.get(keyOf(anchor)) ?? [];
+      const sequenceNumber = Math.max(0, ...list.map((message) => message.sequenceNumber)) + 1;
+      const message: ConversationMessage = {
+        id: `message-memory-${sequenceNumber}-${list.length}`,
+        parentMessageId,
+        authorLabel,
+        content: body.trim(),
+        createdAt: new Date().toISOString(),
+        sequenceNumber,
+      };
+      byAnchor.set(keyOf(anchor), [...list, message]);
+      return message;
+    },
+    counts: async () => new Map([...byAnchor].filter(([key]) => key.startsWith("reference#")).map(([key, list]) => [key.slice("reference#".length), list.length])),
+  };
+}

package/components/conversation-provider.tsx

@@ -0,0 +1,20 @@
+"use client";
+
+import { useMemo, type ReactNode } from "react";
+import { ConversationStoreProvider, createMemoryConversationStore, type ConversationStore } from "./conversation-context";
+import { appendConversationMessage, loadConversationMessages, loadReferenceConversationCounts } from "./news-desk-taxonomy-client";
+
+function networkConversationStore(authorLabel: string): ConversationStore {
+  return {
+    authorLabel,
+    load: loadConversationMessages,
+    append: async ({ anchor, body, parentMessageId }) => (await appendConversationMessage({ anchor, body, parentMessageId })).message,
+    counts: loadReferenceConversationCounts,
+  };
+}
+
+/** Gives the newsroom its conversations: saved to the backend, or kept in memory in the demo. */
+export function ConversationProvider({ authorLabel, demo, children }: { authorLabel: string; demo: boolean; children: ReactNode }) {
+  const store = useMemo(() => (demo ? createMemoryConversationStore(authorLabel) : networkConversationStore(authorLabel)), [authorLabel, demo]);
+  return <ConversationStoreProvider store={store}>{children}</ConversationStoreProvider>;
+}

package/components/conversation-thread.tsx

@@ -0,0 +1,173 @@
+"use client";
+
+import { Loader2Icon, MessageSquarePlusIcon, ReplyIcon, TriangleAlertIcon, CornerDownRightIcon } from "lucide-react";
+import { useMemo, useState } from "react";
+import { buildConversationTree, conversationAge, conversationAuthorName, type ConversationMessage } from "../lib/conversation";
+import { cn } from "../lib/utils";
+import { AutoGrowTextarea } from "./ui/auto-grow-textarea";
+import type { ConversationState } from "./use-conversation";
+
+/** Flat pill buttons, like the feed's: a tone, never an outline. */
+const PILL = "inline-flex min-h-9 items-center justify-center gap-1.5 rounded-full px-3.5 text-sm font-medium outline-none transition-colors focus-visible:ring-2 focus-visible:ring-ring disabled:opacity-50";
+const PILL_PRIMARY = cn(PILL, "bg-[var(--primary)] text-[var(--primary-foreground)]");
+const PILL_QUIET = cn(PILL, "text-muted-foreground hover:text-foreground");
+
+/**
+ * A box for writing a Message. The text clears the moment you post, so the Message shows at once; if the save fails the text comes
+ * back (unless you have typed something new) with the reason, and nothing you wrote is lost.
+ */
+function Composer({ autoFocus = false, buttonLabel, disabledReason, icon, label, onCancel, onSubmit, placeholder }: {
+  autoFocus?: boolean;
+  buttonLabel: string;
+  disabledReason?: string | null;
+  icon: "post" | "reply";
+  label: string;
+  onCancel?: () => void;
+  onSubmit: (body: string) => Promise<void>;
+  placeholder: string;
+}) {
+  const [draft, setDraft] = useState("");
+  const [error, setError] = useState<string | null>(null);
+  const Icon = icon === "post" ? MessageSquarePlusIcon : ReplyIcon;
+  const canPost = !disabledReason && draft.trim().length > 0;
+
+  async function submit() {
+    const text = draft.trim();
+    if (!text || disabledReason) return;
+    setDraft("");
+    setError(null);
+    try {
+      await onSubmit(text);
+      onCancel?.();
+    } catch (failure) {
+      setDraft((current) => current || text);
+      setError(failure instanceof Error ? failure.message : "Your message could not be saved.");
+    }
+  }
+
+  return (
+    <div className="space-y-2" data-conversation-composer={icon}>
+      <AutoGrowTextarea
+        aria-label={label}
+        autoFocus={autoFocus}
+        className="block min-h-16 w-full rounded-[var(--feed-radius-lg,10px)] bg-[var(--feed-control)] p-3 text-base font-normal outline-none placeholder:text-muted-foreground focus-visible:ring-2 focus-visible:ring-ring"
+        disabled={Boolean(disabledReason)}
+        onChange={(event) => setDraft(event.target.value)}
+        onKeyDown={(event) => { if (event.key === "Enter" && (event.metaKey || event.ctrlKey)) { event.preventDefault(); void submit(); } }}
+        placeholder={placeholder}
+        value={draft}
+      />
+      {error ? (
+        <p className="flex items-start gap-1.5 text-sm text-destructive" data-conversation-error role="alert">
+          <TriangleAlertIcon aria-hidden="true" className="mt-0.5 size-4 shrink-0" />
+          <span>Not posted: {error} Your text is kept here.</span>
+        </p>
+      ) : null}
+      {disabledReason ? <p className="text-sm text-muted-foreground">{disabledReason}</p> : null}
+      <div className="flex flex-wrap items-center gap-2">
+        <button className={PILL_PRIMARY} data-conversation-post={icon} disabled={!canPost} onClick={() => void submit()} type="button">
+          <Icon aria-hidden="true" className="size-4" />
+          {buttonLabel}
+        </button>
+        {onCancel ? <button className={PILL_QUIET} onClick={onCancel} type="button">Cancel</button> : null}
+      </div>
+    </div>
+  );
+}
+
+function MessageBody({ answers, message, now, onReply, replying, tone }: {
+  answers?: string | null;
+  message: ConversationMessage;
+  now: number;
+  onReply: () => void;
+  replying: boolean;
+  tone: "root" | "reply";
+}) {
+  return (
+    <div className={cn("space-y-1.5 rounded-[var(--feed-radius-lg,10px)] p-3", tone === "root" ? "bg-[var(--feed-control)]" : "bg-[var(--feed-footer)]")} data-conversation-message={message.id} data-conversation-pending={message.pending || undefined}>
+      <p className="flex flex-wrap items-center gap-x-2 text-sm">
+        <span className="font-semibold" data-conversation-author>{conversationAuthorName(message.authorLabel)}</span>
+        <span className="text-xs text-muted-foreground" data-conversation-age>
+          {message.pending ? (
+            <span className="inline-flex items-center gap-1"><Loader2Icon aria-hidden="true" className="size-3 animate-spin" />Sending</span>
+          ) : conversationAge(message.createdAt, now)}
+        </span>
+      </p>
+      {answers ? (
+        <p className="flex items-center gap-1 text-xs text-muted-foreground" data-conversation-answers>
+          <CornerDownRightIcon aria-hidden="true" className="size-3" />
+          In reply to {answers}
+        </p>
+      ) : null}
+      <p className="whitespace-pre-wrap break-words text-base" data-conversation-content>{message.content}</p>
+      {!message.pending ? (
+        <button aria-expanded={replying} className={cn(PILL_QUIET, "-ml-3")} data-conversation-reply={message.id} onClick={onReply} type="button">
+          <ReplyIcon aria-hidden="true" className="size-4" />
+          Reply
+        </button>
+      ) : null}
+    </div>
+  );
+}
+
+/**
+ * The Messages of one conversation, replies nested one level under their top-level Message, and a box to add another. It knows
+ * nothing about where the Messages come from: the caller loads them and saves a post.
+ */
+export function ConversationThread({ disabledReason = null, error = null, heading = "Messages", messages, now, onPost, onRetry, state = "ready" }: {
+  disabledReason?: string | null;
+  error?: string | null;
+  heading?: string;
+  messages: ReadonlyArray<ConversationMessage>;
+  now: number;
+  onPost: (body: string, parentMessageId: string | null) => Promise<void>;
+  onRetry?: () => void;
+  state?: ConversationState;
+}) {
+  const tree = useMemo(() => buildConversationTree(messages), [messages]);
+  const [replyingTo, setReplyingTo] = useState<string | null>(null);
+  const authorOf = (id: string) => conversationAuthorName(messages.find((message) => message.id === id)?.authorLabel);
+  const toggleReply = (id: string) => setReplyingTo((current) => (current === id ? null : id));
+
+  return (
+    <section aria-label={heading} className="space-y-3" data-conversation-thread>
+      <h3 className="text-sm font-medium">{heading}</h3>
+      {state === "loading" ? <p className="flex items-center gap-1.5 text-sm text-muted-foreground" data-conversation-loading><Loader2Icon aria-hidden="true" className="size-4 animate-spin" />Loading messages</p> : null}
+      {state === "error" ? (
+        <p className="flex flex-wrap items-center gap-2 text-sm text-destructive" role="alert">
+          <TriangleAlertIcon aria-hidden="true" className="size-4" />
+          Messages could not be loaded. {error}
+          {onRetry ? <button className={PILL_QUIET} onClick={onRetry} type="button">Try again</button> : null}
+        </p>
+      ) : null}
+      {state === "ready" && !tree.length ? <p className="text-sm text-muted-foreground" data-conversation-empty>No messages yet. Write down what this made you think.</p> : null}
+      <ul className="space-y-3">
+        {tree.map((root) => (
+          <li className="space-y-2" key={root.message.id}>
+            <MessageBody message={root.message} now={now} onReply={() => toggleReply(root.message.id)} replying={replyingTo === root.message.id} tone="root" />
+            {root.replies.length || replyingTo === root.message.id ? (
+              <ul className="ml-4 space-y-2" data-conversation-replies>
+                {root.replies.map((reply) => (
+                  <li key={reply.message.id}>
+                    <MessageBody answers={reply.answers} message={reply.message} now={now} onReply={() => toggleReply(reply.message.id)} replying={replyingTo === reply.message.id} tone="reply" />
+                    {replyingTo === reply.message.id ? (
+                      <div className="mt-2">
+                        <Composer autoFocus buttonLabel="Reply" disabledReason={disabledReason} icon="reply" label={`Reply to ${authorOf(reply.message.id)}`} onCancel={() => setReplyingTo(null)} onSubmit={(body) => onPost(body, reply.message.id)} placeholder={`Reply to ${authorOf(reply.message.id)}…`} />
+                      </div>
+                    ) : null}
+                  </li>
+                ))}
+                {replyingTo === root.message.id ? (
+                  <li>
+                    <Composer autoFocus buttonLabel="Reply" disabledReason={disabledReason} icon="reply" label={`Reply to ${authorOf(root.message.id)}`} onCancel={() => setReplyingTo(null)} onSubmit={(body) => onPost(body, root.message.id)} placeholder={`Reply to ${authorOf(root.message.id)}…`} />
+                  </li>
+                ) : null}
+              </ul>
+            ) : null}
+          </li>
+        ))}
+      </ul>
+      <Composer buttonLabel="Post" disabledReason={disabledReason} icon="post" label="Add a message" onSubmit={(body) => onPost(body, null)} placeholder="Add a message…" />
+    </section>
+  );
+}

package/components/needs-me-reference-detail.tsx

@@ -11,6 +11,7 @@ import type { NeedsMeEntry } from "../lib/needs-me-items";
 import { DefaultOutcome, Heading, type DetailProps } from "./needs-me-bodies";
 import { decidedChoiceOf } from "./needs-me-shared";
 import { predictionFromDecision, ReviewCard, type CardPrediction } from "./reference-review-card";
+import { ReferenceConversation } from "./reference-conversation";
 import { ReferenceCapturePanel } from "./reference-capture-panel";
 import { useReferenceCapture } from "./reference-capture-client";
 import { ReferenceSourcePreview } from "./reference-source-preview";
@@ -57,6 +58,7 @@ export function ReferenceBody(props: DetailProps & { payload: Extract<NeedsMeEnt
         titleHref={url}
       >
         {payload.decision ? <div data-reference-relevance-decision={lineageId}><ReferenceSuggestionProvenance decision={payload.decision} /></div> : null}
+        <ReferenceConversation disabledReason={disabledReason ? "Editor access is required to write messages." : null} lineageId={lineageId} referenceId={reference.id} title={referenceDisplayTitle(reference)} />
       </ReviewCard>
       <DefaultOutcome item={item} />
       {incomplete ? <p className="text-sm text-muted-foreground" data-needs-me-capture-note>The captured text looks cut off or missing. Read it below. If it is incomplete, choose Paste or correct the text and say whether the capture was complete, or rate the Reference as it is.</p> : null}

package/components/news-desk-taxonomy-client.ts

@@ -10,6 +10,7 @@ import { createLocalPreviewRealPublishedVersions, createLocalPreviewAssignments,
 import { generateClient } from "aws-amplify/data";
 import { testEditorOverrideAllowed } from "../lib/test-editor-override";
 import { downloadData, getUrl } from "aws-amplify/storage";
+import { fetchAuthSession } from "aws-amplify/auth";
 import type { Schema } from "../amplify/data/resource";
 import type { NewsDeskAppendix, NewsDeskCategoryTreeNode } from "../lib/content-types";
 import { createEmptyCategorySteeringDashboard } from "../lib/category-dashboard";
@@ -45,7 +46,19 @@ import type {
   SemanticRelationRecord,
   UserDirectoryEntry,
 } from "../lib/category-repository";
-import { relationTypeKey } from "../lib/semantic-graph";
+import { relationTypeKey, semanticStateKey, semanticVersionKey } from "../lib/semantic-graph";
+import {
+  CONVERSATION_FEED_KEY,
+  REFERENCE_CONVERSATION_KIND,
+  conversationAnchorKey,
+  conversationMessageId,
+  conversationThreadId,
+  conversationThreadKind,
+  createWithSequenceRetry,
+  findOrCreateThread,
+  type ConversationAnchor,
+  type ConversationMessage,
+} from "../lib/conversation";
 import { legacyStageKeysToLoad, type ContentItemVersionRecord } from "../lib/content-item-lifecycle";
 import { getContentItemStageDefinitions } from "../lib/site-brand";
 import { DOCTRINE_DEFINITIONS, getCategoryDoctrineDefinitions, type DoctrineCategory } from "../lib/doctrine";
@@ -103,6 +116,23 @@ const LIST_MESSAGE_THREADS_BY_KIND_AND_UPDATED_AT_QUERY = `
   }
 `;
 
+const LIST_MESSAGE_THREADS_BY_ANCHOR_AND_UPDATED_AT_QUERY = `
+  query ListMessageThreadsByAnchorAndUpdatedAt($primaryAnchorKey: String!, $sortDirection: ModelSortDirection, $limit: Int, $nextToken: String) {
+    listMessageThreadsByAnchorAndUpdatedAt(primaryAnchorKey: $primaryAnchorKey, sortDirection: $sortDirection, limit: $limit, nextToken: $nextToken) {
+      items {
+        id threadKind status title summary primaryAnchorKind primaryAnchorId primaryAnchorLineageId primaryAnchorKey createdBySub createdByUserProfileId createdByLabel messageCount lastMessageId lastMessageAt contextDigest activeResponseMessageId responseLockOwner responseLockExpiresAt metadata createdAt updatedAt newsroomFeedKey
+      }
+      nextToken
+    }
+  }
+`;
+
+const CREATE_SEMANTIC_RELATION_MUTATION = `
+  mutation CreateSemanticRelation($input: CreateSemanticRelationInput!) {
+    createSemanticRelation(input: $input) { id }
+  }
+`;
+
 const LIST_MESSAGES_BY_THREAD_AND_SEQUENCE_QUERY = `
   query ListMessagesByThreadAndSequence($threadId: ID!, $sortDirection: ModelSortDirection, $limit: Int, $nextToken: String) {
     listMessagesByThreadAndSequence(threadId: $threadId, sortDirection: $sortDirection, limit: $limit, nextToken: $nextToken) {
@@ -1388,6 +1418,41 @@ export async function createSectionForumThreadRecord(input: {
   return { created: true, thread: normalizeThreadRecord(response.createMessageThread ?? thread) };
 }
 
+/**
+ * Appends one Message to a thread: the next sequence number, the Message, then the thread's count and last Message. The Message id
+ * derives from the sequence number, so a create that loses a race for the number collides and retries with the next one.
+ */
+async function appendMessageToThread(thread: MessageThreadRecord, build: (sequenceNumber: number, now: string) => MessageRecord): Promise<{ thread: MessageThreadRecord; message: MessageRecord }> {
+  const threadId = thread.id;
+  let now = new Date().toISOString();
+  let built: MessageRecord | null = null;
+  const { created } = await createWithSequenceRetry({
+    list: () => listMessagesByThreadId(threadId, 1000),
+    create: (sequenceNumber) => {
+      now = new Date().toISOString();
+      built = build(sequenceNumber, now);
+      return runGraphql<{ createMessage?: MessageRecord | null }>(CREATE_MESSAGE_MUTATION, { input: built });
+    },
+  });
+  const createdMessage = normalizeMessageRecord(created.createMessage ?? built!);
+  const updated = await runGraphql<{ updateMessageThread?: MessageThreadRecord | null }>(
+    UPDATE_MESSAGE_THREAD_MUTATION,
+    {
+      input: {
+        id: threadId,
+        messageCount: (thread.messageCount ?? 0) + 1,
+        lastMessageId: createdMessage.id,
+        lastMessageAt: createdMessage.createdAt,
+        updatedAt: now,
+      },
+    },
+  );
+  return {
+    thread: normalizeThreadRecord(updated.updateMessageThread ?? { ...thread, updatedAt: now }),
+    message: createdMessage,
+  };
+}
+
 export async function appendForumThreadMessageRecord(input: {
   threadId: string;
   summary: string;
@@ -1404,11 +1469,8 @@ export async function appendForumThreadMessageRecord(input: {
   if (!summary) throw new Error("summary is required");
   if (!content) throw new Error("content is required");
   const thread = await getMessageThreadRecord(threadId);
-  const existing = await listMessagesByThreadId(threadId, 1000);
-  const nextSequence = Math.max(0, ...existing.map((message) => Number(message.sequenceNumber || 0))) + 1;
-  const now = new Date().toISOString();
-  const message: MessageRecord = {
-    id: `message-forum-${safeForumId(threadId)}-${String(nextSequence).padStart(4, "0")}`,
+  return appendMessageToThread(thread, (sequenceNumber, now) => ({
+    id: `message-forum-${safeForumId(threadId)}-${String(sequenceNumber).padStart(4, "0")}`,
     messageKind: "forum_post",
     messageDomain: "edition_coordination",
     status: "active",
@@ -1417,7 +1479,7 @@ export async function appendForumThreadMessageRecord(input: {
     authorLabel: input.authorLabel?.trim() || "editor",
     threadId,
     parentMessageId: input.parentMessageId?.trim() || null,
-    sequenceNumber: nextSequence,
+    sequenceNumber,
     role: input.role || "human",
     messageType: "forum_message",
     content,
@@ -1425,30 +1487,184 @@ export async function appendForumThreadMessageRecord(input: {
     createdAt: now,
     updatedAt: now,
     newsroomFeedKey: "messages",
-  };
-  const created = await runGraphql<{ createMessage?: MessageRecord | null }>(
-    CREATE_MESSAGE_MUTATION,
-    { input: message },
-  );
-  const createdMessage = normalizeMessageRecord(created.createMessage ?? message);
-  const updated = await runGraphql<{ updateMessageThread?: MessageThreadRecord | null }>(
-    UPDATE_MESSAGE_THREAD_MUTATION,
-    {
-      input: {
-        id: threadId,
-        messageCount: (thread.messageCount ?? 0) + 1,
-        lastMessageId: createdMessage.id,
-        lastMessageAt: createdMessage.createdAt,
+  }));
+}
+
+type ConversationAuthor = { sub: string | null; label: string };
+
+async function currentConversationAuthor(): Promise<ConversationAuthor> {
+  const snapshot = await loadReaderSessionSnapshot();
+  let sub: string | null = null;
+  try {
+    const session = await fetchAuthSession();
+    const claim = session.tokens?.idToken?.payload?.sub ?? session.tokens?.accessToken?.payload?.sub;
+    sub = typeof claim === "string" && claim ? claim : null;
+  } catch {
+    sub = null;
+  }
+  return { sub, label: snapshot.auth.status === "signedIn" ? snapshot.auth.label : "editor" };
+}
+
+async function findConversationThread(anchorKey: string): Promise<MessageThreadRecord | null> {
+  type Response = { listMessageThreadsByAnchorAndUpdatedAt?: { items?: Array<MessageThreadRecord | null> | null } | null };
+  const response = await runGraphql<Response>(LIST_MESSAGE_THREADS_BY_ANCHOR_AND_UPDATED_AT_QUERY, {
+    primaryAnchorKey: anchorKey,
+    sortDirection: "DESC",
+    limit: 10,
+  });
+  const found = (response.listMessageThreadsByAnchorAndUpdatedAt?.items ?? []).filter(Boolean) as MessageThreadRecord[];
+  const thread = found.find((entry) => entry.status !== "deleted") ?? null;
+  return thread ? normalizeThreadRecord(thread) : null;
+}
+
+/** The one conversation for an anchor: found by its anchor key, created when there is none. Concurrent first posts share the thread. */
+export async function ensureConversationThread(anchor: ConversationAnchor, author?: ConversationAuthor): Promise<MessageThreadRecord> {
+  const anchorKey = conversationAnchorKey(anchor);
+  if (!anchorKey) throw new Error("An unattached conversation starts its own thread.");
+  return findOrCreateThread({
+    find: () => findConversationThread(anchorKey),
+    create: async () => {
+      const now = new Date().toISOString();
+      const lineageId = anchor.lineageId!.trim();
+      const thread: MessageThreadRecord = {
+        id: conversationThreadId(anchor),
+        threadKind: conversationThreadKind(anchor),
+        status: "active",
+        title: anchor.title?.trim() || lineageId,
+        primaryAnchorKind: anchor.kind,
+        primaryAnchorId: lineageId,
+        primaryAnchorLineageId: lineageId,
+        primaryAnchorKey: anchorKey,
+        createdBySub: author?.sub ?? null,
+        createdByLabel: author?.label ?? "editor",
+        messageCount: 0,
+        lastMessageId: null,
+        lastMessageAt: null,
+        metadata: JSON.stringify({ anchorKind: anchor.kind, anchorLineageId: lineageId }),
+        createdAt: now,
         updatedAt: now,
-      },
+        newsroomFeedKey: CONVERSATION_FEED_KEY,
+      };
+      const response = await runGraphql<{ createMessageThread?: MessageThreadRecord | null }>(CREATE_MESSAGE_THREAD_MUTATION, { input: thread });
+      return normalizeThreadRecord(response.createMessageThread ?? thread);
     },
-  );
+  });
+}
+
+function toConversationMessage(record: MessageRecord): ConversationMessage {
   return {
-    thread: normalizeThreadRecord(updated.updateMessageThread ?? { ...thread, updatedAt: now }),
-    message: createdMessage,
+    id: record.id,
+    parentMessageId: record.parentMessageId ?? null,
+    authorLabel: record.authorLabel ?? "",
+    content: record.content ?? record.body ?? "",
+    createdAt: record.createdAt,
+    sequenceNumber: Number(record.sequenceNumber ?? 0),
   };
 }
 
+/** Every Message in the anchor's conversation, oldest first. An anchor with no conversation yet has none. */
+export async function loadConversationMessages(anchor: ConversationAnchor): Promise<ConversationMessage[]> {
+  const anchorKey = conversationAnchorKey(anchor);
+  if (!anchorKey) return [];
+  const thread = await findConversationThread(anchorKey);
+  if (!thread) return [];
+  const records = await listMessagesByThreadId(thread.id, 500);
+  return records.filter((record) => record.status !== "deleted").map(toConversationMessage);
+}
+
+/** How many Messages each Reference has, from the Reference conversation threads alone (no query per card). Keyed by lineage id. */
+export async function loadReferenceConversationCounts(): Promise<Map<string, number>> {
+  const threads = await listMessageThreadsByKind(REFERENCE_CONVERSATION_KIND, 500);
+  const counts = new Map<string, number>();
+  for (const thread of threads) {
+    const lineageId = thread.primaryAnchorLineageId;
+    if (lineageId && thread.status !== "deleted" && (thread.messageCount ?? 0) > 0) counts.set(lineageId, thread.messageCount ?? 0);
+  }
+  return counts;
+}
+
+/**
+ * Writes a Message into the anchor's conversation (finding or creating the thread), and a `comment` relation from the Message to
+ * the Reference or Item so the thing's own detail can find it. The relation is secondary: if it fails the Message is still saved.
+ */
+export async function appendConversationMessage(input: {
+  anchor: ConversationAnchor;
+  body: string;
+  parentMessageId?: string | null;
+}): Promise<{ message: ConversationMessage; thread: MessageThreadRecord; relationError: string | null }> {
+  const content = String(input.body || "").trim();
+  if (!content) throw new Error("Write something to post.");
+  const author = await currentConversationAuthor();
+  const thread = await ensureConversationThread(input.anchor, author);
+  const result = await appendMessageToThread(thread, (sequenceNumber, now) => ({
+    id: conversationMessageId(thread.id, sequenceNumber),
+    messageKind: "comment",
+    messageDomain: "commentary",
+    status: "active",
+    summary: content.slice(0, 120),
+    source: "newsroom.conversation",
+    authorSub: author.sub,
+    authorLabel: author.label,
+    threadId: thread.id,
+    parentMessageId: input.parentMessageId?.trim() || null,
+    sequenceNumber,
+    role: "human",
+    messageType: "comment",
+    content,
+    metadata: JSON.stringify({ messageKind: "comment", anchorKey: conversationAnchorKey(input.anchor) }),
+    createdAt: now,
+    updatedAt: now,
+    newsroomFeedKey: CONVERSATION_FEED_KEY,
+  }));
+  let relationError: string | null = null;
+  if (input.anchor.kind !== "none") {
+    try {
+      await createCommentRelation(result.message, input.anchor);
+    } catch (error) {
+      relationError = error instanceof Error ? error.message : "The link to the Reference could not be saved.";
+    }
+  }
+  return { message: toConversationMessage(result.message), thread: result.thread, relationError };
+}
+
+async function createCommentRelation(message: MessageRecord, anchor: ConversationAnchor): Promise<void> {
+  if (anchor.kind === "none") return;
+  const lineageId = anchor.lineageId.trim();
+  const objectId = anchor.id?.trim() || lineageId;
+  const now = message.createdAt;
+  await runGraphql(CREATE_SEMANTIC_RELATION_MUTATION, {
+    input: {
+      id: `semantic-relation-${message.id}-comment`,
+      relationState: "current",
+      predicate: "comment",
+      relationTypeId: "semantic-relation-type-comment",
+      relationTypeKey: "comment",
+      relationDomain: "commentary",
+      subjectKind: "message",
+      subjectId: message.id,
+      subjectLineageId: message.id,
+      subjectVersionNumber: 1,
+      objectKind: anchor.kind,
+      objectId,
+      objectLineageId: lineageId,
+      subjectStateKey: semanticStateKey("message", message.id),
+      objectStateKey: semanticStateKey(anchor.kind, lineageId),
+      objectSubjectStateKey: `${semanticStateKey(anchor.kind, lineageId)}#message`,
+      predicateObjectStateKey: `comment#${semanticStateKey(anchor.kind, lineageId)}`,
+      subjectVersionKey: semanticVersionKey("message", message.id),
+      objectVersionKey: semanticVersionKey(anchor.kind, objectId),
+      score: 1,
+      rank: 1,
+      reviewRecommended: false,
+      importedAt: now,
+      createdAt: now,
+      updatedAt: now,
+      newsroomFeedKey: "semanticRelations",
+      metadata: JSON.stringify({ kind: "conversation.comment", messageKind: "comment" }),
+    },
+  });
+}
+
 export async function deleteForumThreadMessageRecord(input: {
   threadId: string;
   messageId: string;

package/components/newsroom-references-view.tsx

@@ -50,6 +50,8 @@ import { FEED_SURFACE_PROPS, FEED_SURFACE_STYLE, ReferenceFeed } from "./referen
 import { ReferenceCapturePanel } from "./reference-capture-panel";
 import { useReferenceCapture, type CorrectCaptureAction } from "./reference-capture-client";
 import { useRatingStore, type RatingController } from "./use-reference-ratings";
+import { ReferenceConversation } from "./reference-conversation";
+import { useReferenceMessageCounts } from "./use-conversation";
 import { captureStatusesByLineage } from "../lib/reference-capture";
 import { applyFeedOrderSnapshot, partitionReferenceFeed, takeFeedOrderSnapshot, type FeedOrderSnapshot, type ReferenceFeedTabKey } from "../lib/reference-feed-ranking";
 import { referenceDek, referencePreviewsByLineage, type ReferencePreview } from "../lib/reference-preview";
@@ -200,6 +202,7 @@ function ReferenceDetailPanel({
   decision,
   demo = false,
   disabled,
+  onMessageCount,
   onReview,
   predictionState = "ready",
   reviewReason,
@@ -223,6 +226,7 @@ function ReferenceDetailPanel({
   decision?: RelevanceDecisionView;
   demo?: boolean;
   disabled?: boolean;
+  onMessageCount?: (lineageId: string, count: number) => void;
   onRelevanceReview?: (curation: RelevanceCuration) => Promise<void> | void;
   onReview: (action: ReferenceCurationAction, options?: ReferenceReviewOptions) => Promise<void> | void;
   predictionState?: PredictionState;
@@ -308,6 +312,7 @@ function ReferenceDetailPanel({
             </details>
           ) : null}
           {delegated ? <DelegatedCurationNote delegated={delegated} referenceLineageId={lineageId} /> : countsAsTrainingLabel ? <CountsAsTrainingLabelNote referenceLineageId={lineageId} /> : null}
+          <ReferenceConversation disabledReason={disabled ? "Editor access is required to write messages." : null} lineageId={lineageId} onCount={onMessageCount} referenceId={reference.id} title={referenceDisplayTitle(reference)} />
         </ReviewCard>
 
         <Separator />
@@ -445,6 +450,7 @@ export function NewsroomReferencesView({
   const [view, setView] = useState<ReferenceView>("feed");
   const [addOpen, setAddOpen] = useState(false);
   const [feedTab, setFeedTab] = useState<ReferenceFeedTabKey>("feed");
+  const { counts: messageCounts, setCount: setMessageCount } = useReferenceMessageCounts(!loading);
   const [visitRated, setVisitRated] = useState<ReadonlySet<string>>(() => new Set());
   const [mountedAt] = useState(() => Date.now());
   const markVisitRated = useCallback((lineageId: string) => {
@@ -774,6 +780,7 @@ export function NewsroomReferencesView({
               <ReferenceFeed
                 disabledReason={feedDisabledReason}
                 loading={previewSkeleton || (loading && !references.length)}
+                messageCounts={messageCounts}
                 now={mountedAt}
                 onOpen={selectReference}
                 onRate={rateFromFeed}
@@ -909,6 +916,7 @@ export function NewsroomReferencesView({
               decision={decisions?.get(referenceLineageId(selectedReference))}
               demo={demo}
               disabled={disabled}
+              onMessageCount={setMessageCount}
               onRelevanceReview={onRelevanceReview ? (curation) => onRelevanceReview(selectedReference, curation) : undefined}
               onReview={runReview}
               sectionAgreement={sectionAgreement}
@@ -952,6 +960,7 @@ export function NewsroomReferencesView({
                   demo={demo}
                   disabled={disabled}
                   onClose={closeDetail}
+                  onMessageCount={setMessageCount}
                   onRelevanceReview={onRelevanceReview ? (curation) => onRelevanceReview(selectedReference, curation) : undefined}
                   onReview={runReview}
                   sectionAgreement={sectionAgreement}

package/components/reference-conversation.tsx

@@ -0,0 +1,43 @@
+"use client";
+
+import { useEffect, useState } from "react";
+import { ConversationThread } from "./conversation-thread";
+import { useConversation } from "./use-conversation";
+
+/**
+ * The Messages about one Reference, under its review card. Shows nothing where no conversation store is provided.
+ * `onCount` tells the feed how many Messages there are, so its card count follows what is written here.
+ */
+export function ReferenceConversation({ disabledReason = null, lineageId, onCount, referenceId, title }: {
+  disabledReason?: string | null;
+  lineageId: string;
+  onCount?: (lineageId: string, count: number) => void;
+  /** The Reference version's id, when it differs from the lineage id. */
+  referenceId?: string;
+  title?: string;
+}) {
+  const conversation = useConversation({ kind: "reference", lineageId, title, ...(referenceId ? { id: referenceId } : {}) });
+  const [now, setNow] = useState(() => Date.now());
+  useEffect(() => {
+    const timer = window.setInterval(() => setNow(Date.now()), 60000);
+    return () => window.clearInterval(timer);
+  }, []);
+  const settled = conversation.messages.filter((message) => !message.pending).length;
+  useEffect(() => {
+    if (conversation.state === "ready") onCount?.(lineageId, settled);
+  }, [conversation.state, lineageId, onCount, settled]);
+  if (!conversation.available) return null;
+  return (
+    <div data-reference-conversation={lineageId}>
+      <ConversationThread
+        disabledReason={disabledReason}
+        error={conversation.error}
+        messages={conversation.messages}
+        now={now}
+        onPost={conversation.post}
+        onRetry={conversation.retry}
+        state={conversation.state}
+      />
+    </div>
+  );
+}

package/components/reference-feed.tsx

@@ -1,6 +1,6 @@
 "use client";
 
-import { InfoIcon, Loader2Icon } from "lucide-react";
+import { InfoIcon, Loader2Icon, MessageSquareIcon } from "lucide-react";
 import { useEffect, useId, useRef, useState, type CSSProperties, type ReactNode } from "react";
 import type { ReferenceRecord } from "../lib/category-repository";
 import { REFERENCE_REJECTION_REASON_CODES, isAutoAccepted, normalizeReferenceCurationStatus, type ReferenceRejectionReasonCode } from "../lib/reference-policy";
@@ -25,6 +25,7 @@ import { CaptureBadge } from "./reference-capture-panel";
 import { AutoAcceptedBadge } from "./auto-accepted-badge";
 import { useRatingStore, type RatingController } from "./use-reference-ratings";
 import type { CaptureStatus } from "../lib/reference-capture";
+import { messageCountLabel } from "../lib/conversation";
 
 /**
  * Flat surfaces, no borders: the page tone, a card tone one step away from it, a footer tone, and a control tone for chips and
@@ -56,6 +57,8 @@ export type ReferenceFeedProps = {
   disabledReason?: string | null;
   /** True while the first read is in flight: cards are skeletons. */
   loading?: boolean;
+  /** How many Messages each Reference has, by lineage id. A card with none shows no count. */
+  messageCounts?: ReadonlyMap<string, number>;
   now: number;
   onOpen: (lineageId: string) => void;
   onRate: (reference: ReferenceRecord, choice: ReviewChoice, reasonCode: ReferenceRejectionReasonCode | null) => Promise<void> | void;
@@ -201,6 +204,7 @@ export function FeedImage({ host, lead, name, src }: { host: string | null; lead
 
 export function FeedCard({
   capture,
+  messageCount = 0,
   decision,
   disabledReason,
   item,
@@ -216,6 +220,8 @@ export function FeedCard({
 }: {
   /** Optional: the capture badge. */
   capture?: CaptureStatus | undefined;
+  /** Optional: how many Messages this Reference has. */
+  messageCount?: number;
   decision: RelevanceDecisionView | undefined;
   disabledReason: string | null;
   item: FeedItem;
@@ -294,6 +300,12 @@ export function FeedCard({
               {host}
             </span>
             {capture ? <CaptureBadge status={capture} /> : null}
+            {messageCount > 0 ? (
+              <span aria-label={messageCountLabel(messageCount)} className="inline-flex items-center gap-1 tabular-nums" data-feed-message-count={messageCount} role="img">
+                <MessageSquareIcon aria-hidden="true" className="size-3.5" />
+                {messageCount}
+              </span>
+            ) : null}
             {isAutoAccepted(reference) ? <AutoAcceptedBadge actor={reference.curationStatusUpdatedBy} reason={reference.curationStatusReason} /> : null}
           </span>
         </span>
@@ -398,6 +410,7 @@ export function SectionHeading({ children, id }: { children: ReactNode; id: stri
 export function ReferenceFeed({
   disabledReason = null,
   loading = false,
+  messageCounts,
   now,
   onOpen,
   onRate,
@@ -426,6 +439,7 @@ export function ReferenceFeed({
       item={item}
       key={item.lineageId}
       lead={lead}
+      messageCount={messageCounts?.get(item.lineageId)}
       now={now}
       onOpen={() => onOpen(item.lineageId)}
       onRate={async (reference, choice, reasonCode) => { onVisitRated(item.lineageId); await onRate(reference, choice, reasonCode); }}

package/components/topic-steering-workspace.tsx

@@ -101,6 +101,7 @@ import { referencePreviewsByLineage } from "../lib/reference-preview";
 import { NewsroomOpsOverview } from "./newsroom-ops-overview";
 import { NewsroomCurationBootstrap } from "./newsroom-curation-bootstrap";
 import { NewsroomReferencesView } from "./newsroom-references-view";
+import { ConversationProvider } from "./conversation-provider";
 import { NewsroomAssignmentsView } from "./newsroom-assignments-view";
 import { NewsroomTopicsView } from "./newsroom-topics-view";
 import { MarkdownContext } from "./markdown-context";
@@ -3049,7 +3050,7 @@ function NewsDeskDashboard({
       : formatDeskSectionHeadline(activeTab);
 
   return (
-    <>
+    <ConversationProvider authorLabel={authState.label} demo={Boolean(dashboard.isDemo)}>
       <NewsroomOpsShell
         activeTab={activeTab}
         appTitle={SITE_BRAND.appTitle}
@@ -3286,7 +3287,7 @@ function NewsDeskDashboard({
         </div>
       </NewsroomOpsShell>
       {topBarSearchControl.dialog}
-    </>
+    </ConversationProvider>
   );
 }
 

package/components/use-conversation.ts

@@ -0,0 +1,84 @@
+"use client";
+
+import { useCallback, useEffect, useRef, useState } from "react";
+import type { ConversationAnchor, ConversationMessage } from "../lib/conversation";
+import { useConversationStore } from "./conversation-context";
+
+export type ConversationState = "loading" | "ready" | "error";
+
+/**
+ * One conversation's Messages. Posting shows the Message at once (marked pending) and swaps in the saved one; a failed save removes
+ * it again and rejects, so the caller can give the typed text back.
+ */
+export function useConversation(anchor: ConversationAnchor) {
+  const store = useConversationStore();
+  const [messages, setMessages] = useState<ConversationMessage[]>([]);
+  const [state, setState] = useState<ConversationState>("loading");
+  const [error, setError] = useState<string | null>(null);
+  const [attempt, setAttempt] = useState(0);
+  const pendingCount = useRef(0);
+  const anchorRef = useRef(anchor);
+  anchorRef.current = anchor;
+  const anchorKey = `${anchor.kind}#${anchor.lineageId ?? ""}`;
+
+  useEffect(() => {
+    if (!store) return;
+    let active = true;
+    setState("loading");
+    setError(null);
+    setMessages([]);
+    store.load(anchorRef.current).then((loaded) => {
+      if (!active) return;
+      setMessages((current) => [...loaded, ...current.filter((message) => message.pending)]);
+      setState("ready");
+    }).catch((failure) => {
+      if (!active) return;
+      setError(failure instanceof Error ? failure.message : "The conversation could not be loaded.");
+      setState("error");
+    });
+    return () => { active = false; };
+  }, [store, anchorKey, attempt]);
+
+  const retry = useCallback(() => setAttempt((current) => current + 1), []);
+
+  const post = useCallback(async (body: string, parentMessageId: string | null) => {
+    if (!store) throw new Error("Messages are not available here.");
+    pendingCount.current += 1;
+    const pendingId = `pending-${pendingCount.current}`;
+    const pending: ConversationMessage = {
+      id: pendingId,
+      parentMessageId,
+      authorLabel: store.authorLabel,
+      content: body.trim(),
+      createdAt: new Date().toISOString(),
+      sequenceNumber: Number.MAX_SAFE_INTEGER - 1000 + pendingCount.current,
+      pending: true,
+    };
+    setMessages((current) => [...current, pending]);
+    try {
+      const saved = await store.append({ anchor: anchorRef.current, body, parentMessageId });
+      setMessages((current) => current.map((message) => (message.id === pendingId ? saved : message)));
+    } catch (failure) {
+      setMessages((current) => current.filter((message) => message.id !== pendingId));
+      throw failure instanceof Error ? failure : new Error("Your message could not be saved.");
+    }
+  }, [store]);
+
+  return { available: Boolean(store), messages, state, error, retry, post };
+}
+
+/** Message counts per Reference lineage, for the feed cards. A failed read just shows no counts. */
+export function useReferenceMessageCounts(enabled: boolean) {
+  const store = useConversationStore();
+  const [counts, setCounts] = useState<ReadonlyMap<string, number>>(() => new Map());
+  useEffect(() => {
+    if (!store || !enabled) return;
+    let active = true;
+    store.counts().then((loaded) => { if (active) setCounts((current) => new Map([...loaded, ...current])); }).catch(() => undefined);
+    return () => { active = false; };
+  }, [store, enabled]);
+  const setCount = useCallback((lineageId: string, count: number) => {
+    setCounts((current) => (current.get(lineageId) === count || (count === 0 && !current.has(lineageId)) ? current : new Map(current).set(lineageId, count)));
+  }, []);
+  return { counts, setCount };
+}

package/lib/conversation.ts

@@ -0,0 +1,154 @@
+/**
+ * Conversations: Messages written about a Reference (later a Story, or nothing at all). One conversation per thing, held in one
+ * MessageThread found by its anchor key. Pure helpers only, so the browser and the tests share them.
+ */
+
+export const CONVERSATION_FEED_KEY = "conversations";
+export const REFERENCE_CONVERSATION_KIND = "reference_conversation";
+export const STORY_CONVERSATION_KIND = "story_conversation";
+export const GENERAL_CONVERSATION_KIND = "conversation";
+
+/** What a conversation is about. `none` is a conversation that is about nothing but itself. */
+export type ConversationAnchor =
+  | { kind: "reference" | "item"; lineageId: string; /** The version id when it differs from the lineage id. */ id?: string; title?: string }
+  | { kind: "none"; lineageId?: undefined; title?: string };
+
+/** A Message as the conversation shows it. */
+export type ConversationMessage = {
+  id: string;
+  parentMessageId: string | null;
+  authorLabel: string;
+  content: string;
+  createdAt: string;
+  sequenceNumber: number;
+  /** True while an optimistic Message waits for the save. */
+  pending?: boolean;
+};
+
+export type ConversationReply = { message: ConversationMessage; answers: string | null };
+export type ConversationRoot = { message: ConversationMessage; replies: ConversationReply[] };
+
+function slug(value: string): string {
+  return value.trim().toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 120) || "thing";
+}
+
+/** `reference#<lineageId>`, `item#<lineageId>`, or null when the conversation is anchored to nothing. */
+export function conversationAnchorKey(anchor: ConversationAnchor): string | null {
+  return anchor.kind === "none" || !anchor.lineageId?.trim() ? null : `${anchor.kind}#${anchor.lineageId.trim()}`;
+}
+
+export function conversationThreadKind(anchor: ConversationAnchor): string {
+  return anchor.kind === "reference" ? REFERENCE_CONVERSATION_KIND : anchor.kind === "item" ? STORY_CONVERSATION_KIND : GENERAL_CONVERSATION_KIND;
+}
+
+/** The thread id follows the anchor, so two editors starting the same conversation at once collide on create instead of splitting it. */
+export function conversationThreadId(anchor: ConversationAnchor): string {
+  const key = conversationAnchorKey(anchor);
+  if (!key) throw new Error("A conversation without an anchor needs its own thread id.");
+  return `message-thread-conversation-${slug(key)}`;
+}
+
+export function conversationMessageId(threadId: string, sequenceNumber: number): string {
+  return `message-conversation-${slug(threadId)}-${String(sequenceNumber).padStart(4, "0")}`;
+}
+
+/** One more than the highest sequence number in use. */
+export function nextConversationSequence(existing: ReadonlyArray<{ sequenceNumber?: number | null }>): number {
+  return Math.max(0, ...existing.map((message) => Number(message.sequenceNumber || 0))) + 1;
+}
+
+/** A create that lost a race for its sequence number (the id derives from the number, so the second writer collides). */
+export function isSequenceConflict(error: unknown): boolean {
+  const text = error instanceof Error ? error.message : typeof error === "string" ? error : JSON.stringify(error ?? "");
+  return /conditional|already exists|duplicate|ConditionalCheckFailed/i.test(text);
+}
+
+/** "ryan@example.test" is shown as "ryan"; a name stays as it is. */
+export function conversationAuthorName(label: string | null | undefined): string {
+  const text = String(label ?? "").trim();
+  if (!text) return "Someone";
+  const at = text.indexOf("@");
+  return at > 0 ? text.slice(0, at) : text;
+}
+
+/**
+ * Top-level Messages in order, each with its replies. A reply to a reply stays flat under the same root and says who it answers.
+ * A reply whose parent is missing is shown as a top-level Message rather than lost.
+ */
+export function buildConversationTree(messages: ReadonlyArray<ConversationMessage>): ConversationRoot[] {
+  const sorted = [...messages].sort((a, b) => a.sequenceNumber - b.sequenceNumber || a.createdAt.localeCompare(b.createdAt));
+  const byId = new Map(sorted.map((message) => [message.id, message]));
+  const rootOf = (message: ConversationMessage): string => {
+    let current = message;
+    const seen = new Set<string>();
+    while (current.parentMessageId && byId.has(current.parentMessageId) && !seen.has(current.id)) {
+      seen.add(current.id);
+      current = byId.get(current.parentMessageId)!;
+    }
+    return current.id;
+  };
+  const roots = new Map<string, ConversationRoot>();
+  for (const message of sorted) {
+    if (rootOf(message) === message.id) roots.set(message.id, { message, replies: [] });
+  }
+  for (const message of sorted) {
+    const root = roots.get(rootOf(message));
+    if (!root || root.message.id === message.id) continue;
+    const parent = message.parentMessageId ? byId.get(message.parentMessageId) : undefined;
+    root.replies.push({ message, answers: parent && parent.id !== root.message.id ? conversationAuthorName(parent.authorLabel) : null });
+  }
+  return [...roots.values()];
+}
+
+/** Short relative time: "now", "5m", "3h", "2d". */
+export function conversationAge(createdAt: string, now: number): string {
+  const time = Date.parse(createdAt);
+  if (!Number.isFinite(time)) return "";
+  const minutes = Math.max(0, Math.round((now - time) / 60000));
+  if (minutes < 1) return "now";
+  if (minutes < 60) return `${minutes}m`;
+  const hours = Math.round(minutes / 60);
+  if (hours < 24) return `${hours}h`;
+  return `${Math.round(hours / 24)}d`;
+}
+
+export function messageCountLabel(count: number): string {
+  return `${count} ${count === 1 ? "message" : "messages"}`;
+}
+
+/**
+ * Creates a Message with the next sequence number. The id derives from the number, so when another writer took it the create is
+ * refused and this tries the next number, up to `attempts` times. `list` returns the Messages already in the thread.
+ */
+export async function createWithSequenceRetry<Message>(input: {
+  list: () => Promise<ReadonlyArray<{ sequenceNumber?: number | null }>>;
+  create: (sequenceNumber: number) => Promise<Message>;
+  attempts?: number;
+}): Promise<{ created: Message; sequenceNumber: number }> {
+  const attempts = input.attempts ?? 5;
+  let sequenceNumber = nextConversationSequence(await input.list());
+  for (let attempt = 1; ; attempt += 1) {
+    try {
+      return { created: await input.create(sequenceNumber), sequenceNumber };
+    } catch (error) {
+      if (!isSequenceConflict(error) || attempt >= attempts) throw error;
+      sequenceNumber = nextConversationSequence(await input.list());
+    }
+  }
+}
+
+/** Finds the conversation's thread, else creates it; a create that loses a race for the (anchor-derived) id uses the winner's thread. */
+export async function findOrCreateThread<Thread>(input: {
+  find: () => Promise<Thread | null>;
+  create: () => Promise<Thread>;
+}): Promise<Thread> {
+  const existing = await input.find();
+  if (existing) return existing;
+  try {
+    return await input.create();
+  } catch (error) {
+    const raced = isSequenceConflict(error) ? await input.find() : null;
+    if (raced) return raced;
+    throw error;
+  }
+}

package/package.json

@@ -80,6 +80,9 @@
     "./components/automation-run-now": "./components/automation-run-now.tsx",
     "./components/automation-view": "./components/automation-view.tsx",
     "./components/blog-page-background": "./components/blog-page-background.tsx",
+    "./components/conversation-context": "./components/conversation-context.tsx",
+    "./components/conversation-provider": "./components/conversation-provider.tsx",
+    "./components/conversation-thread": "./components/conversation-thread.tsx",
     "./components/curation-delegation-client": "./components/curation-delegation-client.ts",
     "./components/dev-sandbox-editor-sign-in": "./components/dev-sandbox-editor-sign-in.tsx",
     "./components/editorial-checks-admin-panel": "./components/editorial-checks-admin-panel.tsx",
@@ -146,6 +149,7 @@
     "./components/reference-add-entry": "./components/reference-add-entry.tsx",
     "./components/reference-capture-client": "./components/reference-capture-client.ts",
     "./components/reference-capture-panel": "./components/reference-capture-panel.tsx",
+    "./components/reference-conversation": "./components/reference-conversation.tsx",
     "./components/reference-curation-controls": "./components/reference-curation-controls.tsx",
     "./components/reference-cyclotron-priming": "./components/reference-cyclotron-priming.tsx",
     "./components/reference-cyclotron-status": "./components/reference-cyclotron-status.tsx",
@@ -189,6 +193,7 @@
     "./components/use-blog-header-obstacles": "./components/use-blog-header-obstacles.ts",
     "./components/use-brand-fonts-ready": "./components/use-brand-fonts-ready.ts",
     "./components/use-console-visibility": "./components/use-console-visibility.ts",
+    "./components/use-conversation": "./components/use-conversation.ts",
     "./components/use-editorial-checks": "./components/use-editorial-checks.ts",
     "./components/use-media-query": "./components/use-media-query.ts",
     "./components/use-near-viewport": "./components/use-near-viewport.ts",
@@ -229,6 +234,7 @@
     "./lib/content-repository": "./lib/content-repository.ts",
     "./lib/content-source-context": "./lib/content-source-context.ts",
     "./lib/content-types": "./lib/content-types.ts",
+    "./lib/conversation": "./lib/conversation.ts",
     "./lib/curation-client": "./lib/curation-client.ts",
     "./lib/curation-delegation-helpers": "./lib/curation-delegation-helpers.ts",
     "./lib/curation-routes": "./lib/curation-routes.ts",
@@ -504,7 +510,7 @@
       "optional": true
     }
   },
-  "version": "5.56.0",
+  "version": "5.57.0",
   "dependencies": {
     "@aws-amplify/adapter-nextjs": "^1.7.3",
     "@aws-crypto/sha256-js": "5.2.0",

package/routes.manifest.json

@@ -1,5 +1,5 @@
 {
-  "version": "5.56.0",
+  "version": "5.57.0",
   "routes": [
     {
       "file": "app/%5F_preview/[[...path]]/route.ts",