@anthusai/papyrus 5.57.0 → 5.59.0

package/lib/reference-feed-ranking.ts

@@ -1,40 +1,22 @@
 /**
- * How the References feed is ordered, and which cards belong in which tab.
- *
- * Plain words, as the "How this feed is ranked" popover says them:
- *   1. The Cyclotron's prediction becomes a probability that you will Accept (P). A prediction of Accept at 80% is
- *      P = 0.8; a prediction of Reject at 80% is P = 0.2; no prediction is P = 0.5.
- *   2. Old items lose their say. The score is 0.5 + (P - 0.5) * w, where w = exp(-age / tau) is a freshness weight.
- *      Age pulls an item toward "uncertain" (0.5), never to the bottom.
- *   3. tau is learned from how old the References you accepted were when you accepted them
- *      (tau = median age / ln 2). With fewer than 10 accepted examples nothing is guessed: no decay.
- *   4. Highest score first. The strongest Reject predictions end up last. Ties go to the newest item.
- *   5. Unrated items older than 3 tau move to "Earlier" at the bottom. Nothing is deleted.
- *
- * The same recipe ranks monitor stories (`learn_freshness` in src/papyrus_content/ideas/monitor_stories.py).
+ * How the References feed is ordered, in plain words (the "How this feed is ranked" popover says them too):
+ *   - One list, two sorts. "Best bets" is the Cyclotron's confidence that you will Accept (P), highest first; a prediction of
+ *     Accept at 80% is P = 0.8, a prediction of Reject at 80% is P = 0.2, no prediction is P = 0.5. Age does not change it.
+ *   - "Newest" is reverse chronological by when the Reference arrived.
+ *   - Ties go to the newest item, then to a stable id order.
+ *   - "Unrated only" shows References nobody has answered; "Include rated" adds the answered ones to the same list.
+ * Nothing is cut off by age, and age never changes the order of Best bets: the original confidence is what ranks.
  */
 import type { ReferenceRecord } from "./category-repository";
 import type { RelevanceDecisionView } from "./relevance-decisions";
-import { isAutoAccepted, normalizeReferenceCurationStatus } from "./reference-policy";
+import { normalizeReferenceCurationStatus } from "./reference-policy";
 import { referenceLineageId } from "./newsroom-references";
 
-/** Fewer accepted examples than this and there is no freshness weight: a constant is never guessed. */
-export const MINIMUM_FRESHNESS_EXAMPLES = 10;
-/** An unrated item whose age passes this many tau has a weight below exp(-3), about 5%, and moves to Earlier. */
-export const EARLIER_AFTER_TAUS = 3;
 /** The probability that stands for "no prediction". */
 export const UNDECIDED_PROBABILITY = 0.5;
 /** A prediction that recorded a label but no confidence is a mild lean, not a coin toss and not a certainty. */
 export const UNRECORDED_CONFIDENCE = 0.6;
 
-const DAY_MILLISECONDS = 86_400_000;
-
-export type FeedFreshness = {
-  /** Null when there were too few accepted examples to learn from: no decay at all. */
-  tauDays: number | null;
-  medianAgeDays: number | null;
-  examples: number;
-};
 
 function timeOf(value: string | null | undefined): number | null {
   if (!value) return null;
@@ -52,35 +34,6 @@ export function referenceDisplayTime(reference: ReferenceRecord): number | null
   return timeOf(reference.sourcePublishedAt) ?? timeOf(reference.sourceUpdatedAt) ?? referenceArrivalTime(reference);
 }
 
-/**
- * tau from the age at acceptance of accepted References: median / ln 2, since the median age of an exponential
- * exp(-age / tau) is tau * ln 2. `ignore` keeps the item an editor just rated from moving the very ranking they are looking at.
- */
-export function learnFreshness(references: ReferenceRecord[], ignore: ReadonlySet<string> = new Set()): FeedFreshness {
-  const ages: number[] = [];
-  for (const reference of references) {
-    if (normalizeReferenceCurationStatus(reference.curationStatus) !== "accepted" || ignore.has(referenceLineageId(reference))) continue;
-    if (isAutoAccepted(reference)) continue; // an automatic acceptance happens after the editors' usual time, so it says nothing about how fast they act
-    const arrived = referenceArrivalTime(reference);
-    const decided = timeOf(reference.curationStatusUpdatedAt);
-    if (arrived === null || decided === null) continue;
-    const age = (decided - arrived) / DAY_MILLISECONDS;
-    if (age > 0) ages.push(age);
-  }
-  if (ages.length < MINIMUM_FRESHNESS_EXAMPLES) return { tauDays: null, medianAgeDays: null, examples: ages.length };
-  ages.sort((left, right) => left - right);
-  const middle = Math.floor(ages.length / 2);
-  const median = ages.length % 2 ? ages[middle] : (ages[middle - 1] + ages[middle]) / 2;
-  return { tauDays: median / Math.LN2, medianAgeDays: median, examples: ages.length };
-}
-
-/** exp(-age / tau) at `now`; 1 without a learned tau or an unreadable arrival. */
-export function freshnessWeight(reference: ReferenceRecord, freshness: FeedFreshness, now: number): number {
-  const arrived = referenceArrivalTime(reference);
-  if (freshness.tauDays === null || arrived === null) return 1;
-  return Math.exp(-Math.max(now - arrived, 0) / DAY_MILLISECONDS / freshness.tauDays);
-}
-
 /** P(the editor accepts), from the Cyclotron's decision: its confidence is in the label it chose. */
 export function acceptProbability(decision: RelevanceDecisionView | undefined): number {
   if (!decision) return UNDECIDED_PROBABILITY;
@@ -93,144 +46,108 @@ export type FeedItem = {
   reference: ReferenceRecord;
   lineageId: string;
   decision: RelevanceDecisionView | undefined;
-  /** P(accept) before freshness. */
+  /** P(accept): the Cyclotron's confidence that the editor accepts. The Best bets sort key. */
   probability: number;
-  weight: number;
-  /** 0.5 + (P - 0.5) * weight. Highest is first. */
-  score: number;
-  /** True when this unrated item is older than the Earlier threshold. */
-  earlier: boolean;
+  /** True when a human has already answered (accepted or rejected). */
+  rated: boolean;
 };
 
-export function scoreFeedItem(reference: ReferenceRecord, decision: RelevanceDecisionView | undefined, freshness: FeedFreshness, now: number): FeedItem {
-  const probability = acceptProbability(decision);
-  const weight = freshnessWeight(reference, freshness, now);
-  const arrived = referenceArrivalTime(reference);
-  const earlier = freshness.tauDays !== null && arrived !== null && (now - arrived) / DAY_MILLISECONDS > EARLIER_AFTER_TAUS * freshness.tauDays;
+export type FeedSort = "best" | "newest";
+export type FeedShow = "unrated" | "all";
+export const DEFAULT_FEED_SORT: FeedSort = "best";
+export const DEFAULT_FEED_SHOW: FeedShow = "unrated";
+
+export function scoreFeedItem(reference: ReferenceRecord, decision: RelevanceDecisionView | undefined): FeedItem {
+  const status = normalizeReferenceCurationStatus(reference.curationStatus);
   return {
     reference,
     lineageId: referenceLineageId(reference),
     decision,
-    probability,
-    weight,
-    score: UNDECIDED_PROBABILITY + (probability - UNDECIDED_PROBABILITY) * weight,
-    earlier,
+    probability: acceptProbability(decision),
+    rated: status === "accepted" || status === "rejected",
   };
 }
 
-/** Highest score first; ties go to the newest item, then to a stable id order. */
-export function compareFeedItems(left: FeedItem, right: FeedItem): number {
-  if (right.score !== left.score) return right.score - left.score;
-  const newest = (referenceDisplayTime(right.reference) ?? 0) - (referenceDisplayTime(left.reference) ?? 0);
-  return newest || left.lineageId.localeCompare(right.lineageId);
+/** Every canonical Reference that is not archived, scored. Unordered: use `orderFeedItems`. */
+export function buildFeedItems(references: ReferenceRecord[], decisions: ReadonlyMap<string, RelevanceDecisionView> | undefined): FeedItem[] {
+  const items: FeedItem[] = [];
+  for (const reference of references) {
+    if (normalizeReferenceCurationStatus(reference.curationStatus) === "archived") continue;
+    items.push(scoreFeedItem(reference, decisions?.get(referenceLineageId(reference))));
+  }
+  return items;
 }
 
-export type ReferenceFeedTabKey = "feed" | "rated" | "earlier";
+/** Best bets: highest P(accept) first; ties go to the newest item, then to a stable id order. */
+export function compareBestBets(left: FeedItem, right: FeedItem): number {
+  if (right.probability !== left.probability) return right.probability - left.probability;
+  return compareNewest(left, right);
+}
 
-export type ReferenceFeedPartition = {
-  freshness: FeedFreshness;
-  /** Pending items, plus the ones rated during this visit (they keep their place), best prediction first. */
-  feed: FeedItem[];
-  /** Everything an editor has answered, most recent answer first. */
-  rated: FeedItem[];
-  /** Unrated items past the freshness threshold, ranked like the feed. Still ratable. */
-  earlier: FeedItem[];
-};
+/** Newest: latest arrival first; ties go to the higher P(accept), then to a stable id order. */
+export function compareNewest(left: FeedItem, right: FeedItem): number {
+  const newest = (referenceArrivalTime(right.reference) ?? 0) - (referenceArrivalTime(left.reference) ?? 0);
+  if (newest) return newest;
+  if (right.probability !== left.probability) return right.probability - left.probability;
+  return left.lineageId.localeCompare(right.lineageId);
+}
 
-/**
- * Splits canonical References into the three tabs.
- * `visitRated` holds lineage ids rated since the page opened: they stay in Feed, in place, showing the answer.
- */
-export function partitionReferenceFeed(
-  references: ReferenceRecord[],
-  decisions: ReadonlyMap<string, RelevanceDecisionView> | undefined,
-  options: { now: number; visitRated?: ReadonlySet<string>; tauDaysOverride?: number | null },
-): ReferenceFeedPartition {
-  const visitRated = options.visitRated ?? new Set<string>();
-  const learned = learnFreshness(references, visitRated);
-  const freshness: FeedFreshness = options.tauDaysOverride && options.tauDaysOverride > 0
-    ? { ...learned, tauDays: options.tauDaysOverride }
-    : learned;
-  const feed: FeedItem[] = [];
-  const rated: FeedItem[] = [];
-  const earlier: FeedItem[] = [];
-  for (const reference of references) {
-    const status = normalizeReferenceCurationStatus(reference.curationStatus);
-    const lineageId = referenceLineageId(reference);
-    const item = scoreFeedItem(reference, decisions?.get(lineageId), freshness, options.now);
-    if (status === "archived") continue;
-    if (status === "accepted" || status === "rejected") {
-      rated.push(item);
-      if (visitRated.has(lineageId)) (item.earlier ? earlier : feed).push(item);
-    } else if (item.earlier) earlier.push(item);
-    else feed.push(item);
-  }
-  feed.sort(compareFeedItems);
-  earlier.sort(compareFeedItems);
-  rated.sort((left, right) => (timeOf(right.reference.curationStatusUpdatedAt) ?? 0) - (timeOf(left.reference.curationStatusUpdatedAt) ?? 0)
-    || left.lineageId.localeCompare(right.lineageId));
-  return { freshness, feed, rated, earlier };
+export function orderFeedItems(items: FeedItem[], sort: FeedSort): FeedItem[] {
+  return [...items].sort(sort === "newest" ? compareNewest : compareBestBets);
 }
 
-export type FeedGroupKey = "top" | "more" | "least";
+/** The visible list: ordered by `sort`; "Unrated only" keeps the items answered during this visit, which stay in place. */
+export function visibleFeedItems(items: FeedItem[], sort: FeedSort, show: FeedShow, visitRated: ReadonlySet<string> = new Set()): FeedItem[] {
+  return orderFeedItems(items.filter((item) => show === "all" || !item.rated || visitRated.has(item.lineageId)), sort);
+}
 
-/**
- * The feed's sections, from the ranked list (already best first). No fixed counts: Top predictions are the Accepts at least half as
- * strong as the strongest one, Least likely are the predicted Rejects, and More for you is everything between (weaker Accepts and
- * items with no prediction). A group with no members is absent.
- */
-export function groupFeedItems(items: FeedItem[]): Array<{ key: FeedGroupKey; items: FeedItem[] }> {
-  const strongest = items.reduce((best, item) => Math.max(best, item.score - UNDECIDED_PROBABILITY), 0);
-  const groups: Record<FeedGroupKey, FeedItem[]> = { top: [], more: [], least: [] };
-  for (const item of items) {
-    const strength = item.score - UNDECIDED_PROBABILITY;
-    if (strength < 0) groups.least.push(item);
-    else if (strength > 0 && strength >= strongest / 2) groups.top.push(item);
-    else groups.more.push(item);
-  }
-  return (["top", "more", "least"] as const).filter((key) => groups[key].length).map((key) => ({ key, items: groups[key] }));
+/** The lead card is the first card, unless it is a predicted Reject. */
+export function feedLeadId(items: FeedItem[]): string | undefined {
+  return items[0] && items[0].probability >= UNDECIDED_PROBABILITY ? items[0].lineageId : undefined;
 }
 
 /**
  * The order of the feed, taken once per visit when it loads and then left alone: selecting, rating, a background refresh and a cache
- * revalidation never re-rank it. Items that arrive later are counted as new and wait behind a "N new items: show" pill.
+ * revalidation never re-rank it, in either sort. Items that arrive later are counted as new and wait behind a "N new items: show" pill.
  */
 export type FeedOrderSnapshot = {
-  /** Every Reference lineage the snapshot knew about (pending, rated and earlier): anything else is new. */
+  /** Every Reference lineage the snapshot knew about: anything else is new. */
   known: ReadonlySet<string>;
-  feed: string[];
-  earlier: string[];
-  groups: Array<{ key: FeedGroupKey; ids: string[] }>;
-  leadId: string | undefined;
+  /** The ones nobody had answered when the snapshot was taken: they stay listed under "Unrated only" after being rated this visit. */
+  unrated: ReadonlySet<string>;
+  best: string[];
+  newest: string[];
+  /** The lead card of each sort, taken with the order: it is never a predicted Reject when the snapshot is taken. */
+  lead: { best: string | undefined; newest: string | undefined };
 };
 
-export function takeFeedOrderSnapshot(partition: ReferenceFeedPartition): FeedOrderSnapshot {
-  const groups = groupFeedItems(partition.feed);
+export function takeFeedOrderSnapshot(items: FeedItem[]): FeedOrderSnapshot {
+  const unrated = items.filter((item) => !item.rated);
+  const best = orderFeedItems(items, "best");
+  const newest = orderFeedItems(items, "newest");
   return {
-    known: new Set([...partition.feed, ...partition.earlier, ...partition.rated].map((item) => item.lineageId)),
-    feed: partition.feed.map((item) => item.lineageId),
-    earlier: partition.earlier.map((item) => item.lineageId),
-    groups: groups.map((group) => ({ key: group.key, ids: group.items.map((item) => item.lineageId) })),
-    leadId: groups[0]?.key !== "least" ? groups[0]?.items[0]?.lineageId : undefined,
+    known: new Set(items.map((item) => item.lineageId)),
+    unrated: new Set(unrated.map((item) => item.lineageId)),
+    best: best.map((item) => item.lineageId),
+    newest: newest.map((item) => item.lineageId),
+    lead: { best: feedLeadId(orderFeedItems(unrated, "best")), newest: feedLeadId(orderFeedItems(unrated, "newest")) },
   };
 }
 
-/** The live partition with its feed order, sections and lead taken from the snapshot; records and scores stay current. */
-export function applyFeedOrderSnapshot(snapshot: FeedOrderSnapshot, live: ReferenceFeedPartition): {
-  partition: ReferenceFeedPartition;
-  groups: Array<{ key: FeedGroupKey; items: FeedItem[] }>;
+/** The visible list in the snapshot's order; records and predictions stay current. */
+export function applyFeedOrderSnapshot(snapshot: FeedOrderSnapshot, live: FeedItem[], sort: FeedSort, show: FeedShow): {
+  items: FeedItem[];
   leadId: string | undefined;
   newCount: number;
 } {
-  const byId = new Map<string, FeedItem>();
-  for (const item of [...live.rated, ...live.earlier, ...live.feed]) byId.set(item.lineageId, item);
-  const pick = (ids: string[]) => ids.flatMap((id) => { const item = byId.get(id); return item ? [item] : []; });
-  const groups = snapshot.groups.map((group) => ({ key: group.key, items: pick(group.ids) })).filter((group) => group.items.length);
-  const newCount = [...live.feed, ...live.earlier].filter((item) => !snapshot.known.has(item.lineageId)).length;
+  const byId = new Map(live.map((item) => [item.lineageId, item] as const));
+  const items = (sort === "newest" ? snapshot.newest : snapshot.best)
+    .filter((id) => show === "all" || snapshot.unrated.has(id))
+    .flatMap((id) => { const item = byId.get(id); return item ? [item] : []; });
+  const lead = snapshot.lead[sort];
   return {
-    partition: { ...live, feed: pick(snapshot.feed), earlier: pick(snapshot.earlier) },
-    groups,
-    leadId: snapshot.leadId && byId.has(snapshot.leadId) ? snapshot.leadId : undefined,
-    newCount,
+    items,
+    leadId: lead && items.some((item) => item.lineageId === lead) ? lead : undefined,
+    newCount: live.filter((item) => !item.rated && !snapshot.known.has(item.lineageId)).length,
   };
 }

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",

package/lib/review-drafts.ts

@@ -44,7 +44,7 @@ export type DraftView = {
 
 export const MAXIMUM_SOURCES = 5;
 const MAXIMUM_EVIDENCE = 3;
-const KIND_WORDS: Record<string, string> = { story_draft: "Story draft", new_concept: "New concept", rename: "Rename", merge: "Merge", split: "Split", new_column: "New column", element_symbol: "Element symbol" };
+const KIND_WORDS: Record<string, string> = { story_draft: "Proposed Story", new_concept: "New concept", rename: "Rename", merge: "Merge", split: "Split", new_column: "New column", element_symbol: "Element symbol" };
 
 /** JSON fields arrive as strings, and a field written through `JSON.stringify` of a string arrives encoded twice: unwrap until it is not text. */
 function parseJson(value: unknown, depth = 0): unknown {
@@ -170,7 +170,7 @@ export function rejectPath(state: string): string[] | null {
 /** The sentence for a draft that cannot move, or null when it can. A hold is named, never hidden. */
 export function cannotMoveReason(view: Pick<DraftView, "state" | "held" | "decided">): string | null {
   if (view.decided) return null;
-  if (view.held) return "This draft is on hold in Proposals. Release the hold there before you decide it.";
+  if (view.held) return "This Proposed Story is on hold in Proposals. Release the hold there before you decide it.";
   return null;
 }
 

package/lib/review-fixture.ts

@@ -18,7 +18,7 @@ export const FIXTURE_REVIEW_REQUESTS: ReviewRequest[] = [
     history: [], appliedIn: null, updatedAt: "2026-10-23T07:00:00Z",
   },
   {
-    id: "rr-soft-1", subject: { type: "proposal", id: "proposal-9" }, mode: "soft_review", reason: "A trend story draft is ready",
+    id: "rr-soft-1", subject: { type: "proposal", id: "proposal-9" }, mode: "soft_review", reason: "A trend Proposed Story is ready",
     ask: null, raisedBy: "trend-pipeline", raisedAt: "2026-10-22T07:00:00Z", deadline: "2026-10-25T07:00:00Z", state: "open", answer: null,
     links: [], history: [], appliedIn: null, updatedAt: "2026-10-22T07:00:00Z",
   },

package/lib/review-requests.ts

@@ -164,12 +164,12 @@ export function nextText(request: ReviewRequest): string {
   if (request.state === "open") {
     if (request.mode === "hard_gate") return "Waiting for you. Nothing continues until you accept or reject.";
     if (request.mode === "soft_review") {
-      if (drafts) return request.deadline ? `Closes on ${formatWhen(request.deadline)} if nobody answers. The drafts stay in Proposals.` : "No deadline. The drafts stay in Proposals until an editor decides them.";
+      if (drafts) return request.deadline ? `Closes on ${formatWhen(request.deadline)} if nobody answers. The Proposed Stories stay in Proposals.` : "No deadline. The Proposed Stories stay in Proposals until an editor decides them.";
       return request.deadline ? `If nobody answers by ${formatWhen(request.deadline)}, this closes and ${request.raisedBy} carries on without a review.` : "No deadline. Stays open until someone answers it.";
     }
     return "Nothing is waiting on this. It stays here until you acknowledge it.";
   }
-  if (request.state === "timed_out") return drafts ? `Closed with no answer on ${formatWhen(request.updatedAt)}. The drafts stay in Proposals.` : `Proceeded without review on ${formatWhen(request.updatedAt)}.`;
+  if (request.state === "timed_out") return drafts ? `Closed with no answer on ${formatWhen(request.updatedAt)}. The Proposed Stories stay in Proposals.` : `Proceeded without review on ${formatWhen(request.updatedAt)}.`;
   if (request.state === "withdrawn") return "Withdrawn by the step that raised it.";
   const answer = request.answer;
   return answer ? `${answerWords(answer, request)} by ${answer.by} on ${formatWhen(answer.at)}.` : "Answered.";
@@ -295,7 +295,7 @@ export function sectionReviews(requests: ReviewRequest[]): NotificationSections
 export type NotificationSummary = { waiting: number; drafts: number; otherReviews: number; decidedBySystem: number; unread: number };
 
 /**
- * "N waiting for you · N AI drafts to review · N other reviews open · N recently decided by the system".
+ * "N waiting for you · N Proposed Stories to review · N other reviews open · N recently decided by the system".
  * Waiting = hard gates plus Cyclotron items held for review (both stay put until a person acts). `draftsToDecide` is the number of
  * drafts in open draft reviews that nobody has decided yet.
  */
@@ -305,7 +305,7 @@ export function summarize(sections: NotificationSections, held: CyclotronEntry[]
 }
 
 export function summaryText(summary: NotificationSummary): string {
-  return `${summary.waiting} waiting for you · ${summary.drafts} AI ${summary.drafts === 1 ? "draft" : "drafts"} to review · ${summary.otherReviews} other ${summary.otherReviews === 1 ? "review" : "reviews"} open · ${summary.decidedBySystem} recently decided by the system`;
+  return `${summary.waiting} waiting for you · ${summary.drafts} ${summary.drafts === 1 ? "Proposed Story" : "Proposed Stories"} to review · ${summary.otherReviews} other ${summary.otherReviews === 1 ? "review" : "reviews"} open · ${summary.decidedBySystem} recently decided by the system`;
 }
 
 export function isUnread(request: ReviewRequest, readIds: ReadonlySet<string>): boolean {

package/lib/semantic-graph.ts

@@ -294,7 +294,7 @@ export class SemanticGraphSnapshot {
   messagesFor(kind: string, lineageId: string): MessageRecord[] {
     const incomingCommentMessages = this.incoming(kind, lineageId)
       .filter((relation) => relation.subjectKind === "message")
-      .filter((relation) => ["comment", "ingestion_rationale"].includes(relationTypeKey(relation)) || ["comment", "ingestion_rationale"].includes(relation.predicate))
+      .filter((relation) => relationTypeKey(relation) === "comment" || relation.predicate === "comment")
       .map((relation) => this.messagesById.get(relation.subjectId))
       .filter((message): message is MessageRecord => Boolean(message));
     const producedMessages = this.outgoing(kind, lineageId)