@anthusai/papyrus 5.56.1 → 5.58.0

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/components/use-reference-ratings.ts

@@ -3,7 +3,7 @@
 import { useCallback, useEffect, useRef, useState } from "react";
 import type { ReferenceRejectionReasonCode } from "../lib/reference-policy";
 import type { ReviewChoice } from "./reference-review-card";
-import type { RatingFeedback } from "./review-rating-grid";
+import type { RatingFeedback } from "./decision-control";
 
 /** How long after the last keystroke a typed reason is saved on its own. */
 export const NOTE_AUTOSAVE_MS = 1200;
@@ -38,8 +38,8 @@ export type RatingController = {
  * shows in both at once. `saved(id)` is the saved human answer; `seed(id)` the saved note and reason code.
  *   vote, then reason  -> the reason is saved onto the existing decision (on blur, or after a short pause)
  *   reason, then vote  -> the vote carries the reason
- * A Reject needs a reason code (the backend refuses one without), so it waits as `pending` until one is chosen; a typed reason is
- * kept in the store until it is saved and is never dropped by a failed save.
+ * A Reject needs a reason (the backend refuses one without): words or a reason code, whichever the surface asks for. With neither it
+ * waits as `pending` until one arrives; a typed reason is kept in the store until it is saved and is never dropped by a failed save.
  */
 export function useRatingStore({ save, saved, seed, needsReason, sticky, saveNote }: {
   save: RatingSave;
@@ -110,13 +110,17 @@ export function useRatingStore({ save, saved, seed, needsReason, sticky, saveNot
 
   const commit = useCallback(async (id: string, choice: ReviewChoice) => {
     if (finalDecision(id)) { void saveNoteOnly(id); return; }
-    const { note, reasonCode: chosenCode } = values(id);
-    // A typed reason is a reason: a Reject with words but no reason button is filed under "other" rather than left waiting.
-    const reasonCode = chosenCode ?? (choice === "reject" && note.trim() ? "other" : null);
-    if (choice === "reject" && !reasonCode && (latest.current.needsReason?.(id) ?? true)) { patch(id, { pending: "reject", askReason: true }); return; }
+    const { note, reasonCode } = values(id);
+    // A typed reason is a reason, so a Reject with words goes at once rather than waiting. It carries no
+    // code the editor did not pick: the backend reads the words for the code they name, and files words
+    // that name none under "other". Only a Reject with neither words nor a code waits for one.
+    if (choice === "reject" && !reasonCode && !note.trim() && (latest.current.needsReason?.(id) ?? true)) { patch(id, { pending: "reject", askReason: true }); return; }
     if (inFlight.current.has(id)) { dirty.current.add(id); return; }
     inFlight.current.add(id);
     dirty.current.delete(id);
+    // The note goes out with this save, so its own pending autosave has nothing left to send.
+    dirty.current.delete(`note:${id}`);
+    clearTimeout(timers.current[id]);
     const started = itemsRef.current[id] ?? EMPTY;
     patch(id, { pending: choice, askReason: false, feedback: { phase: "saving" } });
     try {

package/lib/category-repository.ts

@@ -280,6 +280,13 @@ export type ReferenceRecord = {
   curationStatusUpdatedAt?: string | null;
   curationStatusUpdatedBy?: string | null;
   curationStatusReason?: string | null;
+  /** The latest vote's details; a Reference keeps only its latest vote (earlier votes live in the Cyclotron's feedback). */
+  curationReasonCode?: string | null;
+  curationActorKind?: string | null;
+  curationSectionId?: string | null;
+  curationShareable?: boolean | null;
+  curationDelegation?: unknown;
+  curationDecisionRelationId?: string | null;
   newsroomFeedKey?: string | null;
   reviewedFeedKey?: string | null;
   metadata?: unknown;

package/lib/conversation-feed.ts

@@ -0,0 +1,96 @@
+/**
+ * The Messages page: which MessageThreads are conversations, which section each belongs to, and how several newest-first streams
+ * (one per thread kind) merge into one page of conversations ordered by last activity. Pure helpers, shared by the browser and the tests.
+ */
+import { GENERAL_CONVERSATION_KIND, REFERENCE_CONVERSATION_KIND, STORY_CONVERSATION_KIND } from "./conversation";
+
+export type ConversationSection = "all" | "references" | "stories" | "chats" | "other";
+export const CONVERSATION_SECTIONS: ReadonlyArray<{ key: ConversationSection; label: string }> = [
+  { key: "all", label: "All" },
+  { key: "references", label: "References" },
+  { key: "stories", label: "Stories" },
+  { key: "chats", label: "Chats" },
+  { key: "other", label: "Other" },
+];
+
+export const CHAT_THREAD_KIND = "console";
+export const FORUM_THREAD_KINDS = ["edition_forum", "section_forum"] as const;
+
+/** The thread kinds that are conversations, by section. Machine records (provenance, curation, ingestion rationale) are in none of them. */
+const KINDS_BY_SECTION: Record<Exclude<ConversationSection, "all">, ReadonlyArray<string>> = {
+  references: [REFERENCE_CONVERSATION_KIND],
+  stories: [STORY_CONVERSATION_KIND],
+  chats: [CHAT_THREAD_KIND],
+  other: [GENERAL_CONVERSATION_KIND, ...FORUM_THREAD_KINDS],
+};
+
+export function threadKindsForSection(section: ConversationSection): string[] {
+  if (section === "all") return Object.values(KINDS_BY_SECTION).flat();
+  return [...KINDS_BY_SECTION[section]];
+}
+
+/** The section a thread kind is listed under, or null for a kind that is not a conversation. */
+export function sectionOfThreadKind(kind: string): Exclude<ConversationSection, "all"> | null {
+  for (const [section, kinds] of Object.entries(KINDS_BY_SECTION)) if (kinds.includes(kind)) return section as Exclude<ConversationSection, "all">;
+  return null;
+}
+
+export const SECTION_EMPTY_COPY: Record<ConversationSection, string> = {
+  all: "No conversations yet. Write a message above, or on a Reference, to start one.",
+  references: "No Reference has a message yet. Open a Reference and write down what it made you think.",
+  stories: "No Story has a message yet.",
+  chats: "No chats yet.",
+  other: "No other conversations yet. Write a message above to start one.",
+};
+
+export type PagedThreads<Thread> = { items: Thread[]; nextToken: string | null };
+
+type Streamable = { id: string; updatedAt: string };
+
+/**
+ * One page at a time out of several newest-first streams, merged by `updatedAt` (the order of every thread index). A stream is only
+ * asked for another page when its buffered threads have all been shown, so the order across streams is exact, never approximate.
+ */
+export function createMergedThreadStream<Thread extends Streamable>(
+  kinds: ReadonlyArray<string>,
+  loadPage: (kind: string, nextToken: string | null) => Promise<PagedThreads<Thread>>,
+) {
+  const lanes = kinds.map((kind) => ({ kind, buffer: [] as Thread[], nextToken: null as string | null, started: false, done: false }));
+  const seen = new Set<string>();
+
+  async function fill() {
+    await Promise.all(lanes.filter((lane) => !lane.done && lane.buffer.length === 0).map(async (lane) => {
+      const page = await loadPage(lane.kind, lane.started ? lane.nextToken : null);
+      lane.started = true;
+      lane.nextToken = page.nextToken;
+      lane.done = !page.nextToken;
+      lane.buffer = [...page.items].sort((left, right) => right.updatedAt.localeCompare(left.updatedAt));
+    }));
+  }
+
+  return {
+    /** The next `count` conversations, newest first, and whether more remain. */
+    async next(count: number): Promise<{ items: Thread[]; hasMore: boolean }> {
+      const items: Thread[] = [];
+      while (items.length < count) {
+        await fill();
+        const live = lanes.filter((lane) => lane.buffer.length > 0);
+        if (!live.length) break;
+        // A lane that is not finished and has an empty buffer after a fill returned an empty page with more behind it: ask again.
+        if (lanes.some((lane) => !lane.done && lane.buffer.length === 0)) continue;
+        const best = live.reduce((winner, lane) => (lane.buffer[0].updatedAt.localeCompare(winner.buffer[0].updatedAt) > 0 ? lane : winner));
+        const thread = best.buffer.shift()!;
+        if (seen.has(thread.id)) continue;
+        seen.add(thread.id);
+        items.push(thread);
+      }
+      return { items, hasMore: lanes.some((lane) => lane.buffer.length > 0 || !lane.done) };
+    },
+  };
+}
+
+/** The newest `limit` messages, oldest first, and how many are held back behind "Show all". */
+export function latestMessages<Message>(messages: ReadonlyArray<Message>, limit: number, showAll: boolean): { shown: Message[]; hidden: number } {
+  if (showAll || messages.length <= limit) return { shown: [...messages], hidden: 0 };
+  return { shown: messages.slice(messages.length - limit), hidden: messages.length - limit };
+}

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/lib/cyclotron-suggestions.ts

@@ -1,4 +1,4 @@
-import type { MessageRecord } from "./category-repository";
+import type { ReferenceRecord } from "./category-repository";
 import type { RelevanceCuration, RelevanceDecisionView } from "./relevance-decisions";
 import { safeId } from "./relevance-status";
 
@@ -149,22 +149,12 @@ function parseMetadata(value: unknown): Record<string, unknown> {
 }
 
 /**
- * Reference lineage ids whose latest curation Message was made by a signed-in
- * person. Agent and classifier status changes never appear here, and neither
- * does a reference a person decided before a later non-human change.
+ * Reference lineage ids whose latest vote was made by a signed-in person
+ * (`curationActorKind` is `human`). Agent, Cyclotron and rule votes never appear
+ * here, and neither does a reference a person decided before a later non-human change.
  */
-export function referencesWithHumanLatestCuration(messages: MessageRecord[]): Set<string> {
-  const latestByReference = new Map<string, { createdAt: string; human: boolean }>();
-  for (const message of messages) {
-    if (message.messageKind !== "reference_curation") continue;
-    const metadata = parseMetadata(message.metadata);
-    const lineageId = typeof metadata.referenceLineageId === "string" ? metadata.referenceLineageId : "";
-    if (!lineageId) continue;
-    const seen = latestByReference.get(lineageId);
-    if (seen && seen.createdAt >= message.createdAt) continue;
-    latestByReference.set(lineageId, { createdAt: message.createdAt, human: metadata.actorKind === "human" });
-  }
-  return new Set([...latestByReference].filter(([, entry]) => entry.human).map(([lineageId]) => lineageId));
+export function referencesWithHumanLatestCuration(references: readonly ReferenceRecord[]): Set<string> {
+  return new Set(references.filter((reference) => reference.curationActorKind === "human").map((reference) => reference.lineageId ?? reference.id));
 }
 
 export type SuggestionChoice = "agree" | "overrule";
@@ -233,30 +223,22 @@ export function delegationShortId(delegationId: string): string {
 }
 
 /**
- * Delegated curations by reference lineage, from each reference's latest
- * curation Message only. The person is the Message author; the agent is relayedBy.
+ * Delegated curations by reference lineage, from each Reference's latest vote only.
+ * The person is who set the status (`curationStatusUpdatedBy`); the agent is the delegation's relayedBy.
  */
-export function delegatedCurationsByReference(messages: MessageRecord[]): Map<string, DelegatedCuration> {
-  const latest = new Map<string, MessageRecord>();
-  for (const message of messages) {
-    if (message.messageKind !== "reference_curation") continue;
-    const lineageId = parseMetadata(message.metadata).referenceLineageId;
-    if (typeof lineageId !== "string" || !lineageId) continue;
-    const seen = latest.get(lineageId);
-    if (!seen || seen.createdAt < message.createdAt) latest.set(lineageId, message);
-  }
+export function delegatedCurationsByReference(references: readonly ReferenceRecord[]): Map<string, DelegatedCuration> {
   const delegated = new Map<string, DelegatedCuration>();
-  for (const [lineageId, message] of latest) {
-    const metadata = parseMetadata(message.metadata);
-    if (metadata.attestation !== "delegated") continue;
-    const delegationId = typeof metadata.delegationId === "string" ? metadata.delegationId : "";
-    delegated.set(lineageId, {
-      agent: typeof metadata.relayedBy === "string" && metadata.relayedBy ? metadata.relayedBy : "an agent",
-      person: message.authorLabel?.trim() || null,
-      instruction: typeof metadata.instruction === "string" ? metadata.instruction : "",
+  for (const reference of references) {
+    const delegation = parseMetadata(reference.curationDelegation);
+    if (!Object.keys(delegation).length) continue;
+    const delegationId = typeof delegation.delegationId === "string" ? delegation.delegationId : "";
+    delegated.set(reference.lineageId ?? reference.id, {
+      agent: typeof delegation.relayedBy === "string" && delegation.relayedBy ? delegation.relayedBy : "an agent",
+      person: reference.curationStatusUpdatedBy?.trim() || null,
+      instruction: typeof delegation.instruction === "string" ? delegation.instruction : "",
       delegationId,
       delegationShortId: delegationShortId(delegationId),
-      countsAsTrainingLabel: metadata.actorKind === "human",
+      countsAsTrainingLabel: reference.curationActorKind === "human",
     });
   }
   return delegated;

package/lib/local-preview-seed.ts

@@ -210,15 +210,16 @@ const PREVIEW_CYCLOTRON_ID = "papyrus-relevance";
 /**
  * Fixture data for reviewing the cyclotron suggestion UI without a backend:
  * suggestions with provenance on the first references, a mix of human and
- * non-human curation messages, and a live-agreement payload.
+ * non-human votes recorded on the References, and a live-agreement payload.
  */
 export function createLocalPreviewCyclotronFixtures(references: ReferenceRecord[]): {
   relations: SemanticRelationRecord[];
-  messages: MessageRecord[];
+  /** The first few References with a latest vote recorded on them, by Reference id. */
+  votedReferences: Map<string, ReferenceRecord>;
   shadowAgreement: ShadowAgreement;
 } {
   const relations: SemanticRelationRecord[] = [];
-  const messages: MessageRecord[] = [];
+  const votedReferences = new Map<string, ReferenceRecord>();
   references.slice(0, PREVIEW_SUGGESTION_PLANS.length).forEach((reference, index) => {
     const plan = PREVIEW_SUGGESTION_PLANS[index];
     const lineageId = reference.lineageId ?? reference.id;
@@ -264,35 +265,23 @@ export function createLocalPreviewCyclotronFixtures(references: ReferenceRecord[
       }),
     } as SemanticRelationRecord);
     if (plan.curation !== "none") {
-      const createdAt = isoTimestampHoursBeforeBase(30 - index);
-      messages.push({
-        id: `preview-curation-message-${index}`,
-        messageKind: "reference_curation",
-        messageDomain: "commentary",
-        status: "active",
-        summary: `${reference.title ?? lineageId}: curated`,
-        authorLabel: plan.curation === "delegated" ? "Maya Okafor" : null,
-        source: "newsroom",
-        createdAt,
-        updatedAt: createdAt,
-        metadata: JSON.stringify({
-          action: reference.curationStatus === "rejected" ? "reject" : "accept",
-          curationStatus: reference.curationStatus,
-          referenceLineageId: lineageId,
-          actorKind: plan.curation === "service" ? "service" : "human",
-          ...(plan.curation === "delegated" ? {
-            attestation: "delegated",
-            relayedBy: "newsroom-reporter",
-            delegationId: "curation-delegation-9b1f6c24-5d0e-4a7b-8c31-2e6f0a1d7b45",
-            instruction: "Reject that one, it duplicates the filing from Tuesday.",
-          } : {}),
-        }),
+      // A Reference keeps its latest vote on itself (no Message): the details sit in its curation* fields.
+      votedReferences.set(reference.id, {
+        ...reference,
+        curationStatusUpdatedAt: isoTimestampHoursBeforeBase(30 - index),
+        curationStatusUpdatedBy: plan.curation === "delegated" ? "Maya Okafor" : reference.curationStatusUpdatedBy,
+        curationActorKind: plan.curation === "service" ? "agent" : "human",
+        curationDelegation: plan.curation === "delegated" ? {
+          delegationId: "curation-delegation-9b1f6c24",
+          relayedBy: "newsroom-reporter",
+          instruction: "Reject that one, it duplicates the filing from Tuesday.",
+        } : null,
       });
     }
   });
   return {
     relations,
-    messages,
+    votedReferences,
     shadowAgreement: {
       schema: SHADOW_AGREEMENT_SCHEMA,
       comparisons: 23,

package/lib/reference-feed-keys.ts

@@ -0,0 +1,69 @@
+/**
+ * The keys the References page reads through (docs/reference-feed-indexes.md). The Python twin is
+ * src/papyrus_content/reference_feed_keys.py; scripts/fixtures/reference-feed-key-vectors.json holds the vectors both test.
+ *
+ * `feedStateKey` is "<corpusId>#unrated" (pending) or "<corpusId>#rated" (accepted or rejected); a Reference that is not the current
+ * version, or is archived, has none and is in neither feed. `predictionSortKey` is the Cyclotron's ORIGINAL P(accept), then arrival, then
+ * id; a Reference nobody predicted sorts as 0.5. A vote changes `feedStateKey` and nothing else here.
+ */
+import { normalizeReferenceCurationStatus } from "./reference-policy";
+
+export const UNDECIDED_PROBABILITY = 0.5;
+const EPOCH = "1970-01-01T00:00:00.000Z";
+const ARRIVAL_FIELDS = ["createdAt", "importedAt", "retrievedAt", "sourcePublishedAt", "versionCreatedAt"] as const;
+
+export type ReferenceFeedKeyInput = {
+  id: string;
+  corpusId?: string | null;
+  curationStatus?: string | null;
+  versionState?: string | null;
+  predictedAcceptProbability?: number | null;
+  createdAt?: string | null;
+  importedAt?: string | null;
+  retrievedAt?: string | null;
+  sourcePublishedAt?: string | null;
+  versionCreatedAt?: string | null;
+};
+
+export type ReferenceFeedKeys = {
+  feedStateKey: string | null;
+  feedArrivalAt: string;
+  predictionSortKey: string;
+};
+
+function instant(value: string | null | undefined): string | null {
+  if (!value) return null;
+  const parsed = Date.parse(value);
+  return Number.isFinite(parsed) ? new Date(parsed).toISOString() : null;
+}
+
+export function referenceFeedArrivalAt(reference: ReferenceFeedKeyInput): string {
+  for (const field of ARRIVAL_FIELDS) {
+    const found = instant(reference[field]);
+    if (found) return found;
+  }
+  return EPOCH;
+}
+
+export function referenceFeedStateKey(reference: ReferenceFeedKeyInput): string | null {
+  if (reference.versionState && reference.versionState !== "current") return null;
+  if (!reference.corpusId) return null;
+  const status = normalizeReferenceCurationStatus(reference.curationStatus);
+  if (status === "archived") return null;
+  return `${reference.corpusId}#${status === "pending" ? "unrated" : "rated"}`;
+}
+
+export function predictionSortKeyFor(probability: number | null | undefined, arrival: string, referenceId: string): string {
+  const chosen = probability === null || probability === undefined ? UNDECIDED_PROBABILITY : Math.min(1, Math.max(0, probability));
+  return `${chosen.toFixed(6)}#${arrival}#${referenceId}`;
+}
+
+/** The three feed keys for a Reference as it stands. `probability` overrides the one stored on it. */
+export function referenceFeedKeys(reference: ReferenceFeedKeyInput, probability?: number | null): ReferenceFeedKeys {
+  const arrival = referenceFeedArrivalAt(reference);
+  return {
+    feedStateKey: referenceFeedStateKey(reference),
+    feedArrivalAt: arrival,
+    predictionSortKey: predictionSortKeyFor(probability ?? reference.predictedAcceptProbability, arrival, reference.id),
+  };
+}