@anthusai/papyrus 5.57.0 → 5.58.0

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/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),
+  };
+}

package/lib/reference-policy.ts

@@ -22,6 +22,84 @@ export function isScopeTrainingNegativeReason(code: string): boolean {
   return SCOPE_TRAINING_NEGATIVE_REASON_CODE_SET.has(code);
 }
 
+/**
+ * The phrases an editor writes when they mean one reason code and little else.
+ *
+ * The order matters, and the two scope-training codes come LAST: a sentence
+ * that also names a mechanical reason ("already have it, and off our beat") is
+ * filed under that reason instead. A false scope negative teaches the relevance
+ * classifier something wrong; a missed one only leaves it untaught.
+ *
+ * Each phrase is a whole word or wording, never a fragment, so "slopes" is not
+ * read as "slop". Words that say none of this yield no code at all rather than
+ * the nearest guess.
+ */
+const WRITTEN_REASON_PHRASES: ReadonlyArray<readonly [ReferenceRejectionReasonCode, readonly string[]]> = [
+  ["duplicate", [
+    "duplicate", "duplicates", "duplicated", "duplication", "dupe", "reprint", "reprinted",
+    "already have (it|this|that|the)", "already (got|covered|accepted|registered|ingested|indexed)",
+    "already in (our|the) (corpus|list|feed|knowledge base|library)", "same (source|piece|story) as",
+  ]],
+  ["unavailable", [
+    "paywall", "paywalled", "unavailable", "not available", "no longer (available|online|up|there|reachable)",
+    "behind a (paywall|login|subscription|sign in)", "(dead|broken|404) link", "link is (dead|broken)",
+    "(cannot|cant) (open|read|reach|access|download|retrieve)", "requires a (subscription|login|account|sign in)",
+    "taken down", "timed out", "page is gone",
+  ]],
+  ["provenance", [
+    "provenance", "unattributed", "unverified", "unverifiable", "untraceable",
+    "(cannot|cant) (verify|attribute)", "no (byline|author|citation|attribution|provenance)",
+    "(unknown|unclear|anonymous|missing) (author|source|origin|provenance)", "who wrote it",
+  ]],
+  ["low_quality", [
+    "(low|poor) quality", "poorly (written|sourced|argued|researched|edited)", "badly written", "sloppy",
+    "content farm", "clickbait", "seo (spam|bait|filler)", "slop", "junk", "spam", "no substance", "churnalism",
+  ]],
+  ["policy_exclusion", [
+    "policy exclusion", "(our|house|editorial) policy", "against (our )?policy",
+    "(policy|policies) (excludes?|forbids?|bars?|rules? out|says?)",
+    "(excluded|barred|ruled out|forbidden) by (our )?policy",
+    "we (dont|do not) (cover|run|publish|cite|take)", "not allowed", "disallowed", "prohibited",
+    "blocklist", "blocklisted", "blocked source",
+  ]],
+  ["out_of_scope", [
+    "out of scope", "outside (our|the) (scope|remit|coverage|beat|lane)", "not (in|within) (our|the) scope",
+    "off topic", "nothing to do with", "not (our|the) (beat|subject|topic|area|coverage)",
+    "not relevant", "no longer relevant", "irrelevant", "unrelated", "wrong (beat|subject|topic)",
+  ]],
+];
+
+const WRITTEN_REASON_PATTERNS: ReadonlyArray<readonly [ReferenceRejectionReasonCode, RegExp]> =
+  WRITTEN_REASON_PHRASES.map(([code, phrases]) => [code, new RegExp(`\\b(?:${phrases.join("|")})\\b`)] as const);
+
+/**
+ * The reason code a rejection is filed under when the editor gave none: what
+ * their own words plainly say, else "other".
+ *
+ * Words are a reason — a written sentence is what the editor actually gives
+ * now that there are no reason chips — but "other" is the honest answer for
+ * words that name no policy code, rather than a guess the sentence cannot
+ * support. Blank words are no reason at all, so this yields null and the
+ * caller refuses the rejection.
+ */
+export function rejectionReasonCodeForWrittenReason(writtenReason: unknown): ReferenceRejectionReasonCode | null {
+  const words = normalizeWrittenReason(writtenReason);
+  if (!words) return null;
+  for (const [code, pattern] of WRITTEN_REASON_PATTERNS) {
+    if (pattern.test(words)) return code;
+  }
+  return "other";
+}
+
+/** Lower case, apostrophes dropped ("don't" -> "dont") and every other gap a single space, so phrases match plain prose. */
+function normalizeWrittenReason(value: unknown): string {
+  return String(value ?? "")
+    .toLowerCase()
+    .replace(/['\u2018\u2019]/g, "")
+    .replace(/[^a-z0-9]+/g, " ")
+    .trim();
+}
+
 export function normalizeReferenceCurationStatus(value: unknown, defaultStatus: ReferenceCurationStatus = "pending"): ReferenceCurationStatus {
   const normalized = normalizePolicyToken(value ?? defaultStatus);
   if (normalized === "accepted" || normalized === "accept" || normalized === "ready" || normalized === "trusted") return "accepted";
@@ -61,23 +139,17 @@ export function isEvidenceEligibleReference(reference: Pick<ReferenceRecord, "ve
     && normalizeReferenceCurationStatus(reference?.curationStatus) === "accepted";
 }
 
-export function referenceReasonCode(reference: Pick<ReferenceRecord, "metadata"> | null | undefined, messages: Array<Pick<MessageRecord, "metadata" | "createdAt">> = []): ReferenceRejectionReasonCode | null {
-  const metadataReason = reasonCodeFromMetadata(reference?.metadata);
-  if (metadataReason) return metadataReason;
-  const sortedMessages = [...messages].sort((left, right) => String(right.createdAt ?? "").localeCompare(String(left.createdAt ?? "")));
-  for (const message of sortedMessages) {
-    const reason = reasonCodeFromMetadata(message.metadata);
-    if (reason) return reason;
-  }
-  return null;
+/** The reason code of the Reference's latest vote (`curationReasonCode`), else one recorded in its metadata. */
+export function referenceReasonCode(reference: Pick<ReferenceRecord, "metadata" | "curationReasonCode"> | null | undefined): ReferenceRejectionReasonCode | null {
+  return normalizeReferenceRejectionReasonCode(reference?.curationReasonCode) ?? reasonCodeFromMetadata(reference?.metadata);
 }
 
-export function scopeTrainingLabelForReference(reference: Pick<ReferenceRecord, "versionState" | "curationStatus" | "metadata"> | null | undefined, messages: Array<Pick<MessageRecord, "metadata" | "createdAt">> = []): "positive" | "negative" | null {
+export function scopeTrainingLabelForReference(reference: Pick<ReferenceRecord, "versionState" | "curationStatus" | "metadata" | "curationReasonCode"> | null | undefined): "positive" | "negative" | null {
   if (!reference || reference.versionState !== "current") return null;
   const status = normalizeReferenceCurationStatus(reference.curationStatus);
   if (status === "accepted") return "positive";
   if (status !== "rejected") return null;
-  const reasonCode = referenceReasonCode(reference, messages);
+  const reasonCode = referenceReasonCode(reference);
   return reasonCode && SCOPE_TRAINING_NEGATIVE_REASON_CODE_SET.has(reasonCode) ? "negative" : null;
 }
 

package/lib/reference-review-details.ts

@@ -1,71 +1,35 @@
-import type { HydratedModelPayload, MessageRecord, SemanticRelationRecord } from "./category-repository";
+import type { ReferenceRecord, SemanticRelationRecord } from "./category-repository";
 import { normalizeReferenceRejectionReasonCode, type ReferenceRejectionReasonCode } from "./reference-policy";
 
-function metadataRecord(value: unknown): Record<string, unknown> {
-  if (typeof value === "string") {
-    try { return metadataRecord(JSON.parse(value)); } catch { return {}; }
-  }
-  return value && typeof value === "object" && !Array.isArray(value) ? value as Record<string, unknown> : {};
-}
-
-/** The selected Reference's index is authoritative even when the global feed is truncated. */
+/**
+ * The selected Reference's indexed predictions (the Cyclotron's relevance decisions). The Reference's own latest vote
+ * (`curationActorKind`, `curationReasonCode`, ...) is already on the Reference, so no Message is read.
+ */
 export async function loadReferenceReviewDetails(lineageId: string, read: {
-  relations: (direction: "incoming" | "outgoing") => Promise<SemanticRelationRecord[]>;
-  message: (id: string) => Promise<MessageRecord | null>;
-  payloads: (id: string) => Promise<HydratedModelPayload[]>;
-}): Promise<{ relations: SemanticRelationRecord[]; messages: MessageRecord[] }> {
-  const [outgoing, incoming] = await Promise.all([read.relations("outgoing"), read.relations("incoming")]);
-  const relations = outgoing.filter((relation) => relation.subjectKind === "reference" && relation.subjectLineageId === lineageId);
-  const latest = incoming.filter((relation) => relation.predicate === "comment" && relation.relationState === "current"
-    && relation.subjectKind === "message" && relation.objectKind === "reference" && relation.objectLineageId === lineageId
-    && metadataRecord(relation.metadata).messageKind === "reference_curation")
-    .sort((a, b) => String(b.createdAt ?? b.importedAt ?? "").localeCompare(String(a.createdAt ?? a.importedAt ?? "")))[0];
-  if (!latest) return { relations, messages: [] };
-  const message = await read.message(latest.subjectId);
-  if (!message || message.messageKind !== "reference_curation") throw new Error("The latest reference review could not be loaded.");
-  const payload = (await read.payloads(message.id))
-    .filter((entry) => entry.attachment.role === "metadata" && entry.attachment.ownerKind === "message" && entry.attachment.ownerId === message.id)
-    .sort((a, b) => String(b.attachment.updatedAt ?? "").localeCompare(String(a.attachment.updatedAt ?? "")))[0];
-  if (!payload) throw new Error("The latest reference review metadata could not be loaded.");
-  if (payload.error) throw new Error(payload.error);
-  if (!payload.json || typeof payload.json !== "object" || Array.isArray(payload.json)) {
-    throw new Error("The latest reference review metadata is invalid.");
-  }
-  const hydrated = { ...message, metadata: payload.json };
-  const recordedLineage = metadataRecord(hydrated.metadata).referenceLineageId;
-  if (recordedLineage !== lineageId) throw new Error("The latest review metadata does not match this reference lineage.");
-  return { relations, messages: [hydrated] };
-}
-
-function latestReferenceReviews(messages: MessageRecord[]): Map<string, MessageRecord> {
-  const latest = new Map<string, MessageRecord>();
-  for (const message of messages) {
-    if (message.messageKind !== "reference_curation") continue;
-    const lineage = metadataRecord(message.metadata).referenceLineageId;
-    if (typeof lineage !== "string" || !lineage) continue;
-    if (!latest.has(lineage) || String(message.createdAt).localeCompare(String(latest.get(lineage)!.createdAt)) > 0) latest.set(lineage, message);
-  }
-  return latest;
+  relations: (direction: "outgoing") => Promise<SemanticRelationRecord[]>;
+}): Promise<{ relations: SemanticRelationRecord[] }> {
+  const outgoing = await read.relations("outgoing");
+  return { relations: outgoing.filter((relation) => relation.subjectKind === "reference" && relation.subjectLineageId === lineageId) };
 }
 
-/** A later acceptance or archive clears any earlier rejection reason. */
-export function latestReferenceReviewReasons(messages: MessageRecord[]): Map<string, ReferenceRejectionReasonCode> {
+/** The reason code of each rejected Reference's latest vote. A later acceptance or archive replaced the vote, so it clears the reason. */
+export function latestReferenceReviewReasons(references: readonly ReferenceRecord[]): Map<string, ReferenceRejectionReasonCode> {
   const reasons = new Map<string, ReferenceRejectionReasonCode>();
-  for (const [lineage, message] of latestReferenceReviews(messages)) {
-    const metadata = metadataRecord(message.metadata);
-    const reason = metadata.action === "reject" ? normalizeReferenceRejectionReasonCode(metadata.reasonCode) : null;
-    if (reason) reasons.set(lineage, reason);
+  for (const reference of references) {
+    if (!reference.curationActorKind || reference.curationStatus !== "rejected") continue;
+    const reason = normalizeReferenceRejectionReasonCode(reference.curationReasonCode);
+    if (reason) reasons.set(reference.lineageId ?? reference.id, reason);
   }
   return reasons;
 }
 
-/** Preserve only a Section explicitly recorded on the newest acceptance, never a prediction. */
-export function latestReferenceReviewSections(messages: MessageRecord[]): Map<string, string> {
+/** The Section a person explicitly recorded on a Reference's latest vote when accepting it, never a prediction. */
+export function latestReferenceReviewSections(references: readonly ReferenceRecord[]): Map<string, string> {
   const sections = new Map<string, string>();
-  for (const [lineage, message] of latestReferenceReviews(messages)) {
-    const metadata = metadataRecord(message.metadata);
-    const sectionId = metadata.action === "accept" && typeof metadata.sectionId === "string" ? metadata.sectionId.trim() : "";
-    if (sectionId) sections.set(lineage, sectionId);
+  for (const reference of references) {
+    if (!reference.curationActorKind || reference.curationStatus !== "accepted") continue;
+    const sectionId = reference.curationSectionId?.trim() ?? "";
+    if (sectionId) sections.set(reference.lineageId ?? reference.id, sectionId);
   }
   return sections;
 }

package/lib/relevance-decisions.ts

@@ -149,11 +149,15 @@ export function currentRelevanceDecisions(relations: SemanticRelationRecord[]):
  * any other label, or a review without a label, rejects with the reason code,
  * which the existing scope-training rule turns back into a cyclotron label
  * (out_of_scope and policy_exclusion) or none.
+ *
+ * A rejection must say why, but either way of saying it will do: a reason code,
+ * or the editor's own words, which the curation Lambda reads for the code they
+ * name. Only a rejection with neither is refused.
  */
 export function curationForRelevanceReview(decision: RelevanceDecisionView, review: RelevanceReview): RelevanceCuration {
   const accepted = review.label !== null && review.label === decision.positiveLabel;
-  if (!accepted && !review.reasonCode) {
-    throw new Error("A review that does not accept the reference needs a reason code.");
+  if (!accepted && !review.reasonCode && !review.explanation?.trim()) {
+    throw new Error("A review that does not accept the reference needs a reason code, or a written reason.");
   }
   return {
     action: accepted ? "accept" : "reject",