@anthusai/papyrus 2.0.0-next.11 → 2.0.0-next.110

package/lib/reference-review-details.ts

@@ -0,0 +1,71 @@
+import type { HydratedModelPayload, MessageRecord, 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. */
+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;
+}
+
+/** A later acceptance or archive clears any earlier rejection reason. */
+export function latestReferenceReviewReasons(messages: MessageRecord[]): 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);
+  }
+  return reasons;
+}
+
+/** Preserve only a Section explicitly recorded on the newest acceptance, never a prediction. */
+export function latestReferenceReviewSections(messages: MessageRecord[]): 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);
+  }
+  return sections;
+}

package/lib/reference-review-request.ts

@@ -0,0 +1,14 @@
+/** Hold the lock before invoking a save, including before React can rerender. */
+export function runReferenceReviewRequest(
+  pending: Map<string, Promise<void>>,
+  lineageId: string,
+  save: () => Promise<void>,
+): Promise<void> {
+  const existing = pending.get(lineageId);
+  if (existing) return existing;
+  const request = Promise.resolve().then(save).finally(() => {
+    if (pending.get(lineageId) === request) pending.delete(lineageId);
+  });
+  pending.set(lineageId, request);
+  return request;
+}

package/lib/relevance-decisions.ts

@@ -7,8 +7,12 @@ export type RelevanceProvenance = {
   labelSet: string[];
   doctrineFingerprint: string | null;
   teachingFingerprint: string | null;
-  teachingLabels: number;
-  primingExamples: number;
+  teachingLabels: number | null;
+  primingExamples: number | null;
+  /** Recorded by the shared monitoring router, absent on local sweep provenance. */
+  system?: string;
+  publicationId?: string;
+  output?: string;
 };
 
 /** The relevance cyclotron's current decision about one reference, as the References tab shows it. */
@@ -28,6 +32,7 @@ export type RelevanceDecisionView = {
   /** Thumbs for a two-class decision with a positive label; per-class buttons otherwise. */
   reviewControl: "thumbs" | "labels";
   cyclotronId: string | null;
+  classifierId?: string;
   /** When the cyclotron made the suggestion, if the decision recorded it. */
   decidedAt: string | null;
   /** Null for decisions made before provenance was recorded. */
@@ -44,6 +49,7 @@ export type RelevanceReview = {
 
 /** The existing curation action an editor's review becomes. */
 export type RelevanceCuration = {
+  sectionId?: string | null;
   action: "accept" | "reject";
   reasonCode: string | null;
   note: string | null;
@@ -65,7 +71,7 @@ function parseMetadata(value: unknown): Record<string, unknown> {
 function parseProvenance(value: unknown): RelevanceProvenance | null {
   const record = parseMetadata(value);
   if (!Object.keys(record).length) return null;
-  const count = (entry: unknown) => (Number.isFinite(Number(entry)) ? Number(entry) : 0);
+  const count = (entry: unknown) => typeof entry === "number" && Number.isInteger(entry) && entry >= 0 ? entry : null;
   const text = (entry: unknown) => (typeof entry === "string" && entry ? entry : null);
   return {
     labelSet: Array.isArray(record.labelSet) ? record.labelSet.map(String) : [],
@@ -73,27 +79,52 @@ function parseProvenance(value: unknown): RelevanceProvenance | null {
     teachingFingerprint: text(record.teachingFingerprint),
     teachingLabels: count(record.teachingLabels),
     primingExamples: count(record.primingExamples),
+    ...(text(record.system) ? { system: text(record.system)! } : {}),
+    ...(text(record.publicationId) ? { publicationId: text(record.publicationId)! } : {}),
+    ...(text(record.output) ? { output: text(record.output)! } : {}),
   };
 }
 
+function recordedVersion(value: unknown): number | null {
+  if ((typeof value !== "number" && typeof value !== "string") || String(value).trim() === "") return null;
+  const version = Number(value);
+  return Number.isInteger(version) && version >= 0 ? version : null;
+}
+
+function decisionTime(relation: SemanticRelationRecord): number {
+  const metadata = parseMetadata(relation.metadata);
+  for (const value of [metadata.decidedAt, relation.importedAt, relation.createdAt]) {
+    if (typeof value !== "string") continue;
+    const timestamp = Date.parse(value);
+    if (Number.isFinite(timestamp)) return timestamp;
+  }
+  return 0;
+}
+
 /**
  * Current decisions keyed by reference lineage, from relations the Newsroom
  * already loads: no extra request per row.
  */
 export function currentRelevanceDecisions(relations: SemanticRelationRecord[]): Map<string, RelevanceDecisionView> {
   const decisions = new Map<string, RelevanceDecisionView>();
-  for (const relation of relations) {
-    if (relation.predicate !== RELEVANCE_RELATION || relation.relationState !== "current") continue;
+  // Realtime events can briefly expose both sides of a superseding write. The
+  // result must not depend on list pagination or subscription arrival order.
+  const ordered = [...relations].sort((left, right) => decisionTime(left) - decisionTime(right) || left.id.localeCompare(right.id));
+  for (const relation of ordered) {
+    if (relation.predicate !== RELEVANCE_RELATION || relation.relationState !== "current" || relation.subjectKind !== "reference") continue;
     const metadata = parseMetadata(relation.metadata);
+    if (!relation.subjectLineageId || typeof metadata.label !== "string" || !metadata.label.trim()
+      || typeof metadata.decisionId !== "string" || !metadata.decisionId.trim()) continue;
     const probabilities = parseMetadata(metadata.probabilities);
     const reason = metadata.reviewReason === "program" || metadata.reviewReason === "audit" ? metadata.reviewReason : null;
-    const version = Number(relation.modelVersion ?? metadata.version);
+    const version = recordedVersion(relation.modelVersion ?? metadata.version);
     decisions.set(relation.subjectLineageId, {
       decisionRelationId: relation.id,
-      decisionId: String(metadata.decisionId ?? ""),
-      label: String(metadata.label ?? ""),
-      confidence: typeof relation.confidence === "number" ? relation.confidence : null,
-      version: Number.isFinite(version) ? version : null,
+      decisionId: metadata.decisionId,
+      label: metadata.label,
+      confidence: typeof relation.confidence === "number" && Number.isFinite(relation.confidence)
+        && relation.confidence >= 0 && relation.confidence <= 1 ? relation.confidence : null,
+      version,
       reviewRecommended: Boolean(relation.reviewRecommended),
       reviewReason: reason,
       reviewDetail: typeof metadata.reviewDetail === "string" ? metadata.reviewDetail : null,
@@ -104,6 +135,7 @@ export function currentRelevanceDecisions(relations: SemanticRelationRecord[]):
       question: typeof metadata.question === "string" ? metadata.question : null,
       reviewControl: metadata.reviewControl === "thumbs" ? "thumbs" : "labels",
       cyclotronId: typeof metadata.cyclotronId === "string" ? metadata.cyclotronId : null,
+      ...(relation.classifierId ? { classifierId: relation.classifierId } : {}),
       decidedAt: typeof metadata.decidedAt === "string" ? metadata.decidedAt : null,
       provenance: parseProvenance(metadata.provenance),
     });

package/lib/relevance-status.ts

@@ -52,10 +52,10 @@ export const DEMO_CYCLOTRON_STATUS: CyclotronStatus = {
   },
   calibration: { saysSure: null, isRight: null, gapPoints: null, curve: [] },
   reviewRate: {
-    state: "onboarding", rate: 1, reason: "Onboarding: every decision is reviewed until the cyclotron earns a lower rate.",
+    state: "onboarding", rate: 1, reason: "Getting started: every suggestion is reviewed until suggestions earn a lower review rate.",
     auditFloor: 0.05, confidenceThreshold: 0.7, override: null,
     nextCheckAfterDecisions: 99,
-    nextStep: "Steps down to 50% after 2 more windows of 100 decisions with accuracy on confident decisions of at least 85% (at least 20 reviewed) and a calibration gap under 5 points. Next check in 99 decisions.",
+    nextStep: "Steps down to 50% after 2 more windows of 100 decisions with accuracy on confident decisions of at least 85% (at least 20 reviewed) and a gap under 5 points between how sure suggestions say they are and how often they are right. Next check in 99 decisions.",
     expectedReviewsPerWeek: 1,
   },
   lastChange: null,

package/lib/review-client.ts

@@ -0,0 +1,120 @@
+"use client";
+
+import { generateClient } from "aws-amplify/data";
+import { getCurrentUser } from "aws-amplify/auth";
+import {
+  answerUpdate, isDue, normalizeReviewRow, timeoutUpdate,
+  type AnswerInput, type ReviewRequest,
+} from "./review-requests";
+
+/**
+ * Review requests through the site's own authenticated API (user pool; editors and admins). The condition `state = open`
+ * on every change means two people answering at once, or an answer racing the deadline, cannot both win.
+ */
+
+const FIELDS = "id subject mode reason ask raisedBy raisedAt deadline state answer links history appliedIn updatedAt";
+const MAX_PAGES = 10;
+
+type GraphQLResult = { data?: Record<string, any>; errors?: { message?: string; errorType?: string }[] };
+
+async function run(query: string, variables: Record<string, unknown>): Promise<GraphQLResult> {
+  const client = generateClient({ authMode: "userPool" });
+  try {
+    return (await client.graphql({ query, variables })) as GraphQLResult;
+  } catch (error) {
+    // Amplify throws the response when AppSync returns errors.
+    return (error && typeof error === "object" && "errors" in error ? error : { errors: [{ message: "failed" }] }) as GraphQLResult;
+  }
+}
+
+export type ReviewLoad = { state: "ready"; requests: ReviewRequest[]; readIds: string[]; userKey: string } | { state: "forbidden" } | { state: "unavailable" };
+
+export async function currentUserKey(): Promise<string> {
+  return (await getCurrentUser()).userId;
+}
+
+/** Loads every request (newest pages first), marks due soft reviews as timed out ("proceeded without review"), and reads this user's marks. */
+export async function loadReviews(now: Date = new Date()): Promise<ReviewLoad> {
+  let userKey: string;
+  try {
+    userKey = await currentUserKey();
+  } catch {
+    return { state: "unavailable" };
+  }
+  const rows: Record<string, unknown>[] = [];
+  let nextToken: string | null = null;
+  for (let page = 0; page < MAX_PAGES; page += 1) {
+    const result = await run(
+      `query ListReviews($limit: Int, $nextToken: String) { listReviewRequests(limit: $limit, nextToken: $nextToken) { items { ${FIELDS} } nextToken } }`,
+      { limit: 500, nextToken },
+    );
+    if (result.errors?.some((entry) => /unauthorized|not authorized|forbidden/i.test(`${entry.errorType ?? ""} ${entry.message ?? ""}`))) return { state: "forbidden" };
+    const connection = result.data?.listReviewRequests;
+    if (result.errors?.length || !connection) return { state: "unavailable" };
+    rows.push(...connection.items.filter(Boolean));
+    nextToken = connection.nextToken ?? null;
+    if (!nextToken) break;
+  }
+  const requests = rows.map(normalizeReviewRow);
+  for (const [index, request] of requests.entries()) {
+    if (!isDue(request, now)) continue;
+    const update = timeoutUpdate(request, now);
+    const written = await run(
+      `mutation Expire($input: UpdateReviewRequestInput!, $condition: ModelReviewRequestConditionInput) { updateReviewRequest(input: $input, condition: $condition) { ${FIELDS} } }`,
+      { input: update, condition: { state: { eq: "open" } } },
+    );
+    const row = written.data?.updateReviewRequest;
+    requests[index] = row ? normalizeReviewRow(row) : { ...request, state: "timed_out", updatedAt: String(update.updatedAt), history: JSON.parse(String(update.history)) };
+  }
+  const marks = await run(
+    `query Marks($filter: ModelReviewReadMarkFilterInput, $limit: Int) { listReviewReadMarks(filter: $filter, limit: $limit) { items { requestId } } }`,
+    { filter: { userKey: { eq: userKey } }, limit: 5000 },
+  );
+  const readIds = (marks.data?.listReviewReadMarks?.items ?? []).filter(Boolean).map((mark: { requestId: string }) => mark.requestId);
+  return { state: "ready", requests, readIds, userKey };
+}
+
+/** Records an answer. Throws an Error with a sentence for the page when the request is closed or the write loses a race. */
+export async function answerReviewRequest(request: ReviewRequest, input: AnswerInput, by: string, now: Date = new Date()): Promise<ReviewRequest> {
+  const update = answerUpdate(request, input, by, now);
+  const result = await run(
+    `mutation Answer($input: UpdateReviewRequestInput!, $condition: ModelReviewRequestConditionInput) { updateReviewRequest(input: $input, condition: $condition) { ${FIELDS} } }`,
+    { input: update, condition: { state: { eq: "open" } } },
+  );
+  if (result.errors?.some((entry) => /conditional/i.test(`${entry.errorType ?? ""} ${entry.message ?? ""}`))) {
+    throw new Error("Someone else answered this, or it proceeded at its deadline. Refresh to see the result.");
+  }
+  if (result.errors?.length || !result.data?.updateReviewRequest) throw new Error("Could not save the answer. Nothing was changed.");
+  return normalizeReviewRow(result.data.updateReviewRequest);
+}
+
+/** This user has seen the request. Create the mark; if it exists, refresh it. */
+export async function markReviewRead(userKey: string, requestId: string, now: Date = new Date()): Promise<void> {
+  const input = { id: `${userKey}#${requestId}`, requestId, userKey, readAt: now.toISOString() };
+  const created = await run(
+    `mutation Mark($input: CreateReviewReadMarkInput!) { createReviewReadMark(input: $input) { id } }`, { input });
+  if (created.errors?.length) {
+    await run(`mutation Mark($input: UpdateReviewReadMarkInput!) { updateReviewReadMark(input: $input) { id } }`, { input });
+  }
+}
+
+const MAX_TITLE_LOOKUPS = 40;
+
+/** Titles of the stories that review requests are about, by lineage id, and the ids of stories that no longer exist (no version of the lineage remains). A story that cannot be read simply has no entry (the card falls back to the id). */
+export async function loadStoryTitles(ids: string[]): Promise<{ titles: Record<string, string>; deleted: string[] }> {
+  const titles: Record<string, string> = {};
+  const deleted: string[] = [];
+  await Promise.all([...new Set(ids)].slice(0, MAX_TITLE_LOOKUPS).map(async (id) => {
+    const result = await run(
+      `query StoryTitle($lineageId: ID!) { listItemsByLineageAndVersion(lineageId: $lineageId, limit: 50) { items { versionNumber headline title } } }`,
+      { lineageId: id },
+    );
+    // Only a clean, empty answer means the story is gone; a failed lookup says nothing.
+    if (!result.errors?.length && result.data?.listItemsByLineageAndVersion && !(result.data.listItemsByLineageAndVersion.items ?? []).filter(Boolean).length) deleted.push(id);
+    const items = (result.data?.listItemsByLineageAndVersion?.items ?? []).filter(Boolean) as { versionNumber?: number; headline?: string; title?: string }[];
+    const newest = items.sort((a, b) => (b.versionNumber ?? 0) - (a.versionNumber ?? 0))[0];
+    const title = newest?.headline || newest?.title;
+    if (title) titles[id] = title;
+  }));
+  return { titles, deleted };
+}

package/lib/review-fixture.ts

@@ -0,0 +1,45 @@
+import type { ReviewRequest } from "./review-requests";
+
+/** Demo and test data: one of each mode, a timed-out soft review, and an answered one whose steering was applied. */
+export const FIXTURE_REVIEW_REQUESTS: ReviewRequest[] = [
+  {
+    id: "rr-hard-1", subject: { type: "story", id: "story-ruling-1" }, mode: "hard_gate", reason: "Approve this ruling summary before it is published",
+    ask: "Check the holding and the quoted passages.", raisedBy: "distinctive.ttab.ruling-analysis", raisedAt: "2026-10-23T08:00:00Z", deadline: null,
+    state: "open", answer: null, links: [], history: [{ at: "2026-10-23T08:00:00Z", event: "raised", by: "distinctive.ttab.ruling-analysis", note: "hard_gate" }],
+    appliedIn: null, updatedAt: "2026-10-23T08:00:00Z",
+  },
+  {
+    id: "rr-soft-2", subject: { type: "batch", id: "2026-W43" }, mode: "soft_review", reason: "3 new story ideas to review",
+    ask: "Approve to keep them all, reject to drop the batch, or steer with a note.", raisedBy: "idea-pipeline", raisedAt: "2026-10-23T07:00:00Z",
+    deadline: "2026-10-30T07:00:00Z", state: "open", answer: null,
+    links: [{ type: "proposal", id: "proposal-1", label: "story idea 1" }, { type: "proposal", id: "proposal-2", label: "story idea 2" }, { type: "proposal", id: "proposal-3", label: "story idea 3" }],
+    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",
+    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",
+  },
+  {
+    id: "rr-flag-1", subject: { type: "reference", id: "ref-1" }, mode: "flag", reason: "Two sources disagree about the filing date",
+    ask: null, raisedBy: "reference-intake", raisedAt: "2026-10-22T10:00:00Z", deadline: null, state: "open", answer: null, links: [], history: [],
+    appliedIn: null, updatedAt: "2026-10-22T10:00:00Z",
+  },
+  {
+    id: "rr-late-1", subject: { type: "story", id: "story-old" }, mode: "soft_review", reason: "Check the headline", ask: null, raisedBy: "copy-editor",
+    raisedAt: "2026-10-10T07:00:00Z", deadline: "2026-10-17T07:00:00Z", state: "timed_out", answer: null, links: [],
+    history: [{ at: "2026-10-17T07:00:00Z", event: "timed_out", by: "system", note: "proceeded without review" }], appliedIn: null, updatedAt: "2026-10-17T07:00:00Z",
+  },
+  {
+    id: "rr-done-1", subject: { type: "batch", id: "2026-W42" }, mode: "soft_review", reason: "4 new story ideas to review", ask: null, raisedBy: "idea-pipeline",
+    raisedAt: "2026-10-16T07:00:00Z", deadline: "2026-10-23T07:00:00Z", state: "answered",
+    answer: { decision: "feedback", feedback: "Fewer listicles", steer: "not_this_kind", by: "Ed Itor", at: "2026-10-17T09:00:00Z" },
+    links: [], history: [], appliedIn: { runId: "run-w43", by: "idea-pipeline", at: "2026-10-20T07:00:00Z" }, updatedAt: "2026-10-17T09:00:00Z",
+  },
+  {
+    id: "rr-done-2", subject: { type: "proposal", id: "proposal-4" }, mode: "soft_review", reason: "A concept rename was proposed", ask: null, raisedBy: "concept-bot",
+    raisedAt: "2026-10-18T07:00:00Z", deadline: "2026-10-25T07:00:00Z", state: "answered",
+    answer: { decision: "feedback", feedback: "Keep the old name for sports", steer: "adjust", by: "Ed Itor", at: "2026-10-19T09:00:00Z" },
+    links: [], history: [], appliedIn: null, updatedAt: "2026-10-19T09:00:00Z",
+  },
+];

package/lib/review-requests.ts

@@ -0,0 +1,246 @@
+/**
+ * The Notification Center's model (PPY-1cd261, PPY-ab6a50): review requests, the Cyclotron items that wait for a person,
+ * the auto-decided stream, and the words the page says about each. Pure functions only, so the page and its tests share them.
+ *
+ * Principle (docs/notification-center.md): everything except a hard gate keeps moving if nobody acts. Each entry says in words
+ * what happens next without the reader, and only a hard gate says "Waiting for you".
+ */
+import type { ReferenceRecord } from "./category-repository";
+import { getNewsroomNavHref } from "./newsroom-nav";
+import { referenceDisplayTitle, referenceLineageId } from "./newsroom-references";
+import { normalizeReferenceCurationStatus } from "./reference-policy";
+import type { RelevanceDecisionView } from "./relevance-decisions";
+
+export type ReviewMode = "flag" | "soft_review" | "hard_gate";
+export type ReviewState = "open" | "answered" | "timed_out" | "withdrawn";
+export type ReviewDecision = "approve" | "acknowledge" | "reject" | "feedback";
+export type ReviewSteer = "adjust" | "not_this_kind";
+
+export type ReviewAnswer = { decision: ReviewDecision; feedback: string | null; steer: ReviewSteer | null; by: string; at: string };
+export type ReviewHistoryEntry = { at: string; event: string; by?: string; note?: string };
+export type ReviewLink = { label?: string; url?: string; type?: string; id?: string };
+
+export type ReviewRequest = {
+  id: string;
+  subject: { type: string; id: string };
+  mode: ReviewMode;
+  reason: string;
+  ask: string | null;
+  raisedBy: string;
+  raisedAt: string;
+  deadline: string | null;
+  state: ReviewState;
+  answer: ReviewAnswer | null;
+  links: ReviewLink[];
+  history: ReviewHistoryEntry[];
+  appliedIn: { runId: string; by: string; at: string; note?: string | null } | null;
+  updatedAt: string;
+};
+
+export const PROCEEDED_WITHOUT_REVIEW = "proceeded without review";
+const MAX_HISTORY = 50;
+
+function parseJson<T>(value: unknown, fallback: T): T {
+  if (typeof value === "string") {
+    try {
+      return JSON.parse(value) as T;
+    } catch {
+      return fallback;
+    }
+  }
+  return value === null || value === undefined ? fallback : (value as T);
+}
+
+/** A row from the API (JSON fields arrive as strings) as a request. */
+export function normalizeReviewRow(row: Record<string, unknown>): ReviewRequest {
+  return {
+    id: String(row.id),
+    subject: parseJson(row.subject, { type: "unknown", id: "" }),
+    mode: row.mode as ReviewMode,
+    reason: String(row.reason ?? ""),
+    ask: typeof row.ask === "string" ? row.ask : null,
+    raisedBy: String(row.raisedBy ?? ""),
+    raisedAt: String(row.raisedAt ?? ""),
+    deadline: typeof row.deadline === "string" ? row.deadline : null,
+    state: row.state as ReviewState,
+    answer: parseJson<ReviewAnswer | null>(row.answer, null),
+    links: parseJson<ReviewLink[]>(row.links, []),
+    history: parseJson<ReviewHistoryEntry[]>(row.history, []),
+    appliedIn: parseJson(row.appliedIn, null),
+    updatedAt: String(row.updatedAt ?? row.raisedAt ?? ""),
+  };
+}
+
+// --- the deadline (checked on read) ---------------------------------------------------------------------
+
+export function isDue(request: ReviewRequest, now: Date): boolean {
+  return request.mode === "soft_review" && request.state === "open" && request.deadline !== null && new Date(request.deadline).getTime() <= now.getTime();
+}
+
+/** The update that marks a due soft review as timed out, "proceeded without review". Applied with the condition state = open. */
+export function timeoutUpdate(request: ReviewRequest, now: Date): Record<string, unknown> {
+  const at = now.toISOString();
+  const history = [...request.history, { at, event: "timed_out", by: "system", note: PROCEEDED_WITHOUT_REVIEW }].slice(-MAX_HISTORY);
+  return { id: request.id, state: "timed_out", updatedAt: at, history: JSON.stringify(history) };
+}
+
+export type AnswerInput = { decision: ReviewDecision; feedback?: string | null; steer?: ReviewSteer | null };
+
+/** The update for an answer, or an Error saying why it is refused. Applied with the condition state = open. */
+export function answerUpdate(request: ReviewRequest, input: AnswerInput, by: string, now: Date): Record<string, unknown> {
+  if (request.state !== "open") throw new Error(`This request is ${request.state.replace("_", " ")}${request.state === "timed_out" ? ` (${PROCEEDED_WITHOUT_REVIEW})` : ""} and can no longer be answered.`);
+  if (input.decision === "acknowledge" && request.mode !== "flag") throw new Error("Only a flag is acknowledged; approve or reject this one.");
+  const feedback = input.feedback?.trim() || null;
+  const steer = input.steer ?? null;
+  if (input.decision === "feedback" && !feedback && !steer) throw new Error("Write a note, or choose \"Not this kind of thing\".");
+  const at = now.toISOString();
+  const answer: ReviewAnswer = { decision: input.decision, feedback, steer, by, at };
+  const history = [...request.history, { at, event: "answered", by, note: input.decision }].slice(-MAX_HISTORY);
+  return { id: request.id, state: "answered", answer: JSON.stringify(answer), updatedAt: at, history: JSON.stringify(history) };
+}
+
+// --- words ------------------------------------------------------------------------------------------------
+
+export function formatWhen(iso: string | null | undefined): string {
+  if (!iso) return "";
+  const date = new Date(iso);
+  if (Number.isNaN(date.getTime())) return "";
+  return `${date.toISOString().slice(0, 10)} ${date.toISOString().slice(11, 16)} UTC`;
+}
+
+export function modeLabel(mode: ReviewMode): string {
+  return mode === "hard_gate" ? "Hard gate" : mode === "soft_review" ? "Soft review" : "Flag";
+}
+
+/** A mark and the words, never colour alone. */
+export function modeMark(mode: ReviewMode): string {
+  return mode === "hard_gate" ? "■" : mode === "soft_review" ? "◐" : "⚑";
+}
+
+/** What happens next without the reader. Only a hard gate says "Waiting for you". */
+export function nextText(request: ReviewRequest): string {
+  if (request.state === "open") {
+    if (request.mode === "hard_gate") return "Waiting for you. Nothing continues until you approve or reject.";
+    if (request.mode === "soft_review") return `Proceeds automatically on ${formatWhen(request.deadline)} unless you steer it.`;
+    return "Nothing is waiting on this. It stays here until you acknowledge it.";
+  }
+  if (request.state === "timed_out") return `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.";
+}
+
+export function answerWords(answer: ReviewAnswer, request?: Pick<ReviewRequest, "mode">): string {
+  if (answer.steer === "not_this_kind") return "Steered: not this kind of thing";
+  if (answer.decision === "acknowledge") return "Acknowledged";
+  if (answer.decision === "approve") return request?.mode === "flag" ? "Acknowledged" : "Approved";
+  if (answer.decision === "reject") return "Rejected";
+  return "Steered with a note";
+}
+
+/** "You steered X, applied in run Y": what became of a person's input. */
+export function steeringText(request: ReviewRequest): string | null {
+  const answer = request.answer;
+  if (request.state !== "answered" || !answer || !(answer.feedback || answer.steer || answer.decision === "reject")) return null;
+  const said = answer.feedback ? `"${answer.feedback}"` : answerWords(answer).toLowerCase();
+  if (request.appliedIn) return `You steered ${said}. Applied in run ${request.appliedIn.runId} on ${formatWhen(request.appliedIn.at)}.`;
+  return `You steered ${said}. ${request.raisedBy} has not used it yet; it will on its next run.`;
+}
+
+/** What a request is about, in words: a story shows its title (the id when the title is not known), anything else its type and id. */
+export function subjectLabel(subject: { type: string; id: string }, titles: Readonly<Record<string, string>> = {}, deleted: ReadonlySet<string> = new Set()): string {
+  if (subject.type === "story") return deleted.has(subject.id) ? `story ${subject.id} (story deleted)` : titles[subject.id] ?? `story ${subject.id}`;
+  return `${subject.type.replace("_", " ")} ${subject.id}`;
+}
+
+export function subjectHref(subject: { type: string; id: string }, demo = false): string | null {
+  const id = encodeURIComponent(subject.id);
+  if (subject.type === "story") return getNewsroomNavHref(`/newsroom/articles/${id}`, demo);
+  if (subject.type === "reference" || subject.type === "cyclotron_decision") return getNewsroomNavHref(`/newsroom/references/${id}`, demo);
+  if (subject.type === "proposal") return getNewsroomNavHref(`/newsroom/topics?proposal=${id}`, demo);
+  if (subject.type === "automation_run") return getNewsroomNavHref("/newsroom/administration/automations", demo);
+  return null;
+}
+
+// --- Cyclotron items ---------------------------------------------------------------------------------------
+
+export type CyclotronEntry = {
+  lineageId: string;
+  title: string;
+  label: string;
+  confidence: number | null;
+  decidedAt: string | null;
+  reviewDetail: string | null;
+  reviewedByPerson: boolean;
+  href: string;
+};
+
+function cyclotronEntry(reference: ReferenceRecord, decision: RelevanceDecisionView, reviewed: ReadonlySet<string>, demo: boolean): CyclotronEntry {
+  const lineageId = referenceLineageId(reference);
+  return {
+    lineageId, title: referenceDisplayTitle(reference), label: decision.label, confidence: decision.confidence,
+    decidedAt: decision.decidedAt, reviewDetail: decision.reviewDetail, reviewedByPerson: reviewed.has(lineageId),
+    href: getNewsroomNavHref(`/newsroom/references/${encodeURIComponent(lineageId)}`, demo),
+  };
+}
+
+/** Items the Cyclotron routed to a person (the References tab's own rule: review recommended and still pending). Least confident first. */
+export function cyclotronHeldForReview(references: ReferenceRecord[], decisions: ReadonlyMap<string, RelevanceDecisionView>, demo = false): CyclotronEntry[] {
+  const entries: CyclotronEntry[] = [];
+  for (const reference of references) {
+    const decision = decisions.get(referenceLineageId(reference));
+    if (decision?.reviewRecommended && normalizeReferenceCurationStatus(reference.curationStatus) === "pending") {
+      entries.push(cyclotronEntry(reference, decision, new Set(), demo));
+    }
+  }
+  return entries.sort((a, b) => (a.confidence ?? 1) - (b.confidence ?? 1));
+}
+
+/** Recent classifications the Cyclotron made on its own confidence. Read only here; correcting happens on the reference. Newest first. */
+export function cyclotronAutoDecided(references: ReferenceRecord[], decisions: ReadonlyMap<string, RelevanceDecisionView>, reviewed: ReadonlySet<string>, demo = false, limit = 20): CyclotronEntry[] {
+  const entries: CyclotronEntry[] = [];
+  for (const reference of references) {
+    const decision = decisions.get(referenceLineageId(reference));
+    if (decision && !decision.reviewRecommended) entries.push(cyclotronEntry(reference, decision, reviewed, demo));
+  }
+  return entries.sort((a, b) => (b.decidedAt ?? "").localeCompare(a.decidedAt ?? "")).slice(0, limit);
+}
+
+// --- the page's shape -------------------------------------------------------------------------------------------
+
+export type NotificationSections = {
+  hardGates: ReviewRequest[];
+  softReviews: ReviewRequest[];
+  flags: ReviewRequest[];
+  /** Answered, timed out or withdrawn, newest first: what people said and what became of it. */
+  decided: ReviewRequest[];
+};
+
+export function sectionReviews(requests: ReviewRequest[]): NotificationSections {
+  const open = requests.filter((request) => request.state === "open");
+  const byRaised = (a: ReviewRequest, b: ReviewRequest) => a.raisedAt.localeCompare(b.raisedAt);
+  return {
+    hardGates: open.filter((request) => request.mode === "hard_gate").sort(byRaised),
+    softReviews: open.filter((request) => request.mode === "soft_review").sort((a, b) => (a.deadline ?? "").localeCompare(b.deadline ?? "")),
+    flags: open.filter((request) => request.mode === "flag").sort((a, b) => b.raisedAt.localeCompare(a.raisedAt)),
+    decided: requests.filter((request) => request.state !== "open").sort((a, b) => b.updatedAt.localeCompare(a.updatedAt)),
+  };
+}
+
+export type NotificationSummary = { waiting: number; proceedingSoon: number; decidedBySystem: number; unread: number };
+
+/**
+ * "N waiting for you · N proceeding soon · N recently decided by the system".
+ * Waiting = hard gates plus Cyclotron items held for review (both stay put until a person acts). Proceeding soon = open soft reviews.
+ */
+export function summarize(sections: NotificationSections, held: CyclotronEntry[], autoDecided: CyclotronEntry[], unread: number): NotificationSummary {
+  return { waiting: sections.hardGates.length + held.length, proceedingSoon: sections.softReviews.length, decidedBySystem: autoDecided.length, unread };
+}
+
+export function summaryText(summary: NotificationSummary): string {
+  return `${summary.waiting} waiting for you · ${summary.proceedingSoon} proceeding soon · ${summary.decidedBySystem} recently decided by the system`;
+}
+
+export function isUnread(request: ReviewRequest, readIds: ReadonlySet<string>): boolean {
+  return !readIds.has(request.id);
+}

package/lib/semantic-graph.ts

@@ -57,6 +57,7 @@ export type SemanticPredicateId =
   | "related_to"
   | "broader_than"
   | "narrower_than"
+  | "member_of"
   | "supports"
   | "contradicts";
 
@@ -96,6 +97,7 @@ export const SEMANTIC_PREDICATES: SemanticPredicateDefinition[] = [
   { id: "related_to", label: "related to", group: "generic", inverseLabel: "related from" },
   { id: "broader_than", label: "broader than", group: "ontology", inverseLabel: "narrower concept" },
   { id: "narrower_than", label: "narrower than", group: "ontology", inverseLabel: "broader concept" },
+  { id: "member_of", label: "member of", group: "ontology", inverseLabel: "members" },
   { id: "supports", label: "supports", group: "evidence", inverseLabel: "supported by" },
   { id: "contradicts", label: "contradicts", group: "evidence", inverseLabel: "contradicted by" },
 ];